# MCP servers (/cli/mcp-servers)

Connect external Model Context Protocol (MCP) servers so workflows can use their tools.

To serve Sim workflows to MCP clients instead, use [workflow MCP servers](/cli/workflow-mcp-servers).

`sim mcp-servers` is also spelled `sim mcp-server`.

These commands accept the [global options](/cli/commands#global-options).

## Server connections \[#server-connections]

### List MCP servers \[#list-mcp-servers]

```bash
sim mcp-servers list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--search <value>` | No | Case-insensitive substring match against the server name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listMcpServers](/api-reference/mcp-servers/listMcpServers).

### Get MCP server \[#get-mcp-server]

```bash
sim mcp-servers get <mcpServerId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `mcpServerId` | Yes | Unique MCP server identifier. |

API request and response schemas: [getMcpServer](/api-reference/mcp-servers/getMcpServer).

### Create MCP server \[#create-mcp-server]

```bash
sim mcp-servers create [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | Yes | Server display name. |
| `--description <value>` | No | Optional server description. |
| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
| `--url <value>` | Yes | Absolute HTTP or HTTPS endpoint URL without `{{ENV_VAR}}` references. It determines server identity and is immutable: delete and recreate the server to change endpoints. |
| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
| `--no-enabled` | No | Send --enabled as false. |
| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |

API request and response schemas: [createMcpServer](/api-reference/mcp-servers/createMcpServer).

### Update MCP server \[#update-mcp-server]

```bash
sim mcp-servers update <mcpServerId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `mcpServerId` | Yes | Unique MCP server identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | No | Server display name. |
| `--description <value>` | No | Optional server description. |
| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
| `--url <value>` | No | Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints. |
| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
| `--no-enabled` | No | Send --enabled as false. |
| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |

API request and response schemas: [updateMcpServer](/api-reference/mcp-servers/updateMcpServer).

## Tool discovery \[#tool-discovery]

### List MCP server tools \[#list-mcp-server-tools]

OAuth login or personal API key required.

```bash
sim mcp-servers tools list <mcpServerId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `mcpServerId` | Yes | Unique MCP server identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--refresh` | No | Refresh tools using your credentials. Otherwise results may reuse another workspace member's recent discovery and omit newly added tools. |
| `--no-refresh` | No | Send --refresh as false. |

API request and response schemas: [listMcpServerTools](/api-reference/mcp-servers/listMcpServerTools).

## Remove servers \[#remove-servers]

### Delete MCP server \[#delete-mcp-server]

This removes the MCP server and the tools it provides.

```bash
sim mcp-servers delete <mcpServerId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `mcpServerId` | Yes | Unique MCP server identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteMcpServer](/api-reference/mcp-servers/deleteMcpServer).

## Related docs \[#related-docs]

- [MCP connections](/agents/mcp)