> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# MCP Servers

> Create, read and update MCP servers through the Moveworks Configuration API.

`platform.extensions.mcp-workspace.servers`

An MCP server entry connects a remote Model Context Protocol server so the assistant can use its tools.

To learn what MCP servers do, see [MCP Servers](/tool-studio/mcp-workspace) in the Tool Studio docs.

* **Endpoint:** `/platform/extensions/mcp-workspace/servers`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch with `version: {num, change_description}` from your last read. Lists of objects merge row by row, so read first and send the whole list when you remove or reorder rows. See [Tool Studio](/api-reference/configuration-api/tool-studio/overview#how-updates-work).
* **References:** Uses an HTTP connector through `connector_id` (the connector's `id`). Productivity assistants refer to the server by its `id` in `mcp_server_ids`.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                              | Endpoint reference                                                                              |
| ------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `GET`   | `/platform/extensions/mcp-workspace/servers`      | [List MCP servers](/api-reference/configuration-api/tool-studio/mcp-servers/list-mcp-servers)   |
| `POST`  | `/platform/extensions/mcp-workspace/servers`      | [Create MCP server](/api-reference/configuration-api/tool-studio/mcp-servers/create-mcp-server) |
| `GET`   | `/platform/extensions/mcp-workspace/servers/{id}` | [Get MCP server](/api-reference/configuration-api/tool-studio/mcp-servers/get-mcp-server)       |
| `PATCH` | `/platform/extensions/mcp-workspace/servers/{id}` | [Update MCP server](/api-reference/configuration-api/tool-studio/mcp-servers/update-mcp-server) |

### Rules the API checks

* `name` and `connector_id` are required, and `name` is unique in your organization.
* The connector must use an auth type that MCP servers support: `oauth2` with `authorization_code_grant` and `pkce_algorithm: OAUTH2_PKCE_ALGORITHM_SHA256`.
* `enabled` defaults to `false`. Set it to `true` to make the server available.
* `launch_config` sets the audience with at most one of `allow_all`, `allowed_users`, `blocked_users` or `allowlist_rule_dsl`. `allow_all: false` means no one can use it.
* Changes to the server's tools show up in new conversations only.

### Fields

| Field                    | Type           | Required  | Notes                                                                                                                                                                                                                                                                                    |
| ------------------------ | -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | string         | read-only | Unique identifier of the MCP server, assigned by the server.                                                                                                                                                                                                                             |
| `name`                   | string         | ✅         | Display name of the MCP server. Must be unique within the organization; up to 128 characters.                                                                                                                                                                                            |
| `connector_id`           | string         | ✅         | Connector that provides the MCP server's base URL and authentication. The connector must use an authentication type supported for MCP servers. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors).                                                           |
| `path`                   | string         |           | Path appended to the connector's base URL to reach the MCP endpoint, for example '/mcp'. Must start with '/' when set.                                                                                                                                                                   |
| `enabled`                | boolean        |           | If true, the MCP server is available for use. Defaults to false.                                                                                                                                                                                                                         |
| `description`            | string         |           | Description of what this MCP server does. Up to 1024 characters.                                                                                                                                                                                                                         |
| `launch_config`          | LaunchSettings |           | Which users the MCP server and its tools are available to. If no audience is set, it is available to all users.                                                                                                                                                                          |
| `tool_confirmation_mode` | enum           |           | When users must confirm before a tool on this server runs: always, never, or server-guided. Defaults to server-guided, which follows the server's own tool annotations. One of: `TOOL_CONFIRMATION_MODE_ALWAYS`, `TOOL_CONFIRMATION_MODE_NEVER`, `TOOL_CONFIRMATION_MODE_SERVER_GUIDED`. |
| `updated_time`           | string         | read-only | When the configuration was last updated.                                                                                                                                                                                                                                                 |
| `updated_by`             | string         | read-only | Who last updated the configuration.                                                                                                                                                                                                                                                      |
| `version`                | Version        | ✅         | Document version. On update, send back the num from your last read.                                                                                                                                                                                                                      |

### Example create body

```json
{
  "name": "internal_tools_mcp",
  "description": "Internal tooling MCP server.",
  "connector_id": "6f1c9f0e-6e1a-4b39-9a1e-1c6d0f2b7a55",
  "path": "/mcp",
  "enabled": true,
  "launch_config": {
    "allowed_users": {
      "email_addrs": [
        "jordan.lee@example.com"
      ]
    }
  },
  "tool_confirmation_mode": "TOOL_CONFIRMATION_MODE_SERVER_GUIDED",
  "version": {
    "change_description": "Initial version."
  }
}
```