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

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

Parameters

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

Response

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

SDK Usage

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

{
  "github": {
    "status": "needs_auth"
  }
}

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

SDK Usage

// 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

{
  "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"
}

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

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

SDK Usage

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

{
  "status": "connected"
}

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

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

SDK Usage

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

{
  "status": "connected"
}

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

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

SDK Usage

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

true

SDK Usage

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

true

SDK Usage

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

{
  "success": true
}

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

SDK Usage

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