# Agent: MCP

**Page:** api/agent/mcp

[Download Raw Markdown](./api/agent/mcp.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# Agent: MCP

Manage Model Context Protocol (MCP) server connections within a workspace — add new servers, connect or disconnect them, and handle OAuth authentication flows.

## Get MCP status


Returns a map of server name to status object describing the current state of every MCP server in the workspace.


`GET /api/v1/workspaces/{workspaceID}/mcp`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |

### Response



```json
{
  "filesystem": {
    "status": "connected"
  },
  "github": {
    "status": "needs_auth"
  },
  "weather": {
    "status": "failed",
    "error": "Connection refused"
  },
  "internal-docs": {
    "status": "disabled"
  }
}
```



### SDK Usage

```ts
const status = await client.agent.mcp.getStatus({
  workspaceID: "ws_01HXYZ..."
});
```

---

## Add MCP server

`POST /api/v1/workspaces/{workspaceID}/mcp`

Dynamically register a new MCP server. The `config` field accepts either a local command-based configuration or a remote URL-based configuration.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Unique name for the MCP server |
| `config` | object | Yes | Server configuration. Either a local config (`McpLocalConfig`) or a remote config (`McpRemoteConfig`) |

**Local config (`McpLocalConfig`)**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Must be `"local"` |
| `command` | array (string) | Yes | Command and arguments to run the MCP server |
| `environment` | object (string → string) | No | Environment variables to set when running the server |
| `enabled` | boolean | No | Enable or disable the MCP server on startup |
| `timeout` | integer | No | Timeout in ms for MCP server requests. Defaults to `5000` (5 seconds) if not specified. Must be greater than `0`. |

**Remote config (`McpRemoteConfig`)**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | Must be `"remote"` |
| `url` | string | Yes | URL of the remote MCP server |
| `enabled` | boolean | No | Enable or disable the MCP server on startup |
| `headers` | object (string → string) | No | Headers to send with the request |
| `oauth` | object \| boolean | No | OAuth configuration (`McpOAuthConfig`) or `false` to disable OAuth auto-detection |
| `timeout` | integer | No | Timeout in ms for MCP server requests. Defaults to `5000` (5 seconds) if not specified. Must be greater than `0`. |

**OAuth config (`McpOAuthConfig`)**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clientId` | string | No | OAuth client ID. If not provided, dynamic client registration (RFC 7591) will be attempted. |
| `clientSecret` | string | No | OAuth client secret (if required by the authorization server) |
| `scope` | string | No | OAuth scopes to request during authorization |

### Response



```json
{
  "github": {
    "status": "needs_auth"
  }
}
```


```json
{
  "data": null,
  "errors": [
    {
      "field": "name",
      "message": "A server with this name already exists"
    }
  ],
  "success": false
}
```



### SDK Usage

```ts
// Local (stdio) MCP server
await client.agent.mcp.addServer({
  workspaceID: "ws_01HXYZ...",
  data: {
    name: "filesystem",
    config: {
      type: "local",
      command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"],
      enabled: true,
      timeout: 10000
    }
  }
});

// Remote MCP server
await client.agent.mcp.addServer({
  workspaceID: "ws_01HXYZ...",
  data: {
    name: "github",
    config: {
      type: "remote",
      url: "https://mcp.example.com/github",
      enabled: true,
      headers: {
        "X-Api-Key": "secret-key"
      },
      oauth: {
        scope: "read:user repo"
      }
    }
  }
});
```

---

## Start MCP OAuth

`POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth`

Begin the OAuth flow for an MCP server. The returned `authorizationUrl` should be opened in a browser to grant access.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `name` | path | string | Yes | The MCP server name |

### Response



```json
{
  "authorizationUrl": "https://auth.example.com/oauth/authorize?response_type=code&client_id=demo&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=read%3Auser&state=abc123"
}
```


```json
{
  "data": null,
  "errors": [
    {
      "message": "OAuth is not supported for local MCP servers"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "MCP server 'github' not found in workspace 'ws_01HXYZ...'"
  }
}
```



### SDK Usage

```ts
const result = await client.agent.mcp.startOAuth({
  workspaceID: "ws_01HXYZ...",
  name: "github"
});

// Open result.authorizationUrl in the user's browser
```

---

## Authenticate MCP OAuth

`POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth/authenticate`

Start the OAuth flow and wait for the callback to complete (the platform opens the browser and captures the redirect).

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `name` | path | string | Yes | The MCP server name |

### Response



```json
{
  "status": "connected"
}
```


```json
{
  "data": null,
  "errors": [
    {
      "message": "OAuth authentication timed out"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "MCP server 'github' not found in workspace 'ws_01HXYZ...'"
  }
}
```



### SDK Usage

```ts
const status = await client.agent.mcp.authenticateOAuth({
  workspaceID: "ws_01HXYZ...",
  name: "github"
});
```

---

## Complete MCP OAuth

`POST /api/v1/workspaces/{workspaceID}/mcp/{name}/auth/callback`

Complete OAuth authentication for an MCP server by providing the authorization code received from the OAuth provider's redirect.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `name` | path | string | Yes | The MCP server name |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | Yes | Authorization code from OAuth callback |

### Response



```json
{
  "status": "connected"
}
```


```json
{
  "data": null,
  "errors": [
    {
      "field": "code",
      "message": "Authorization code is invalid or has expired"
    }
  ],
  "success": false
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "MCP server 'github' not found in workspace 'ws_01HXYZ...'"
  }
}
```



### SDK Usage

```ts
const status = await client.agent.mcp.completeOAuth({
  workspaceID: "ws_01HXYZ...",
  name: "github",
  data: {
    code: "auth_code_from_redirect"
  }
});
```

---

## Connect an MCP server

`POST /api/v1/workspaces/{workspaceID}/mcp/{name}/connect`

Open a live connection to a previously registered MCP server. Servers that require authentication will return a `needs_auth` status if the OAuth flow has not been completed.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `name` | path | string | Yes | The MCP server name |

### Response



```json
true
```



### SDK Usage

```ts
const connected = await client.agent.mcp.connect({
  workspaceID: "ws_01HXYZ...",
  name: "github"
});
```

---

## Disconnect an MCP server

`POST /api/v1/workspaces/{workspaceID}/mcp/{name}/disconnect`

Close an active MCP server connection. The server configuration is preserved and can be reconnected later.

### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `name` | path | string | Yes | name path parameter |
| `workspaceID` | path | string | Yes | workspaceID path parameter |


### Response



```json
true
```



### SDK Usage

```ts
await client.agent.mcp.disconnect({
  workspaceID: "ws_01HXYZ...",
  name: "github"
});
```

---

## Remove MCP OAuth

`DELETE /api/v1/workspaces/{workspaceID}/mcp/{name}/auth`

Delete stored OAuth credentials for an MCP server. The server remains registered, but it will need to be re-authenticated before connecting.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `name` | path | string | Yes | The MCP server name |

### Response



```json
{
  "success": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "MCP server 'github' not found in workspace 'ws_01HXYZ...'"
  }
}
```



### SDK Usage

```ts
await client.agent.mcp.removeOAuth({
  workspaceID: "ws_01HXYZ...",
  name: "github"
});
```

---

## MCP status reference

The `MCPStatus` type is a tagged union. Every status object includes a `status` field whose string value identifies the variant:

| Status value | Additional fields | Meaning |
|--------------|-------------------|---------|
| `"connected"` | — | The server is connected and ready to use |
| `"disabled"` | — | The server is registered but disabled |
| `"failed"` | `error` (string) | The last connection attempt failed |
| `"needs_auth"` | — | The server requires OAuth authentication |
| `"needs_client_registration"` | `error` (string) | Dynamic client registration must be performed first |