MCP Servers

MCP is an open protocol that lets a service expose tools to a model. Connecting an MCP server to the workspace makes all of its tools available in the catalog , ready to hand to any agent.

The usual flow has three steps:

POST /v1/tools/mcp/preview        → see what the server exposes
POST /v1/tools/mcp                → connect it and install what you want
POST /v1/agents/{agentId}/tools   → give them to an agent

Advertencia

Server credentials (tokens, auth headers, OAuth tokens) are stored encrypted and are never returned in any response. You will only ever see the authType and the names of custom headers.

Nota

For security, MCP servers must resolve to public addresses. Localhost, private networks, link-local and cloud-metadata addresses, and redirects to those targets are blocked.

Preview MCP Server

Connects to the server, negotiates transport, and lists its tools. Saves nothing — this is the lookahead call for deciding what to install.

POST https://api.platica.mx/v1/tools/mcp/preview

Request Body

{
  "url": "https://mcp.example.com/mcp",
  "auth": {
    "type": "bearer",
    "token": "sk_live_xxx"
  }
}

Parameter	Type	Description	Required	Default
`url`	string	MCP server URL. Must be `https`	✓	—
`auth`	object	Server authentication. See below	—	`{ "type": "none" }`
`headers`	object	Extra handshake headers, as `name: value` pairs	—	—

No authentication

{ "type": "none" }

Bearer token

{ "type": "bearer", "token": "sk_live_xxx" }

API key in a header

{
  "type": "apikey-header",
  "token": "sk_live_xxx",
  "headerName": "X-Api-Key",
  "headerPrefix": ""
}

headerPrefix is the text placed before the token; leave it empty when the header carries only the value.

OAuth 2

{ "type": "oauth2", "scope": "read write" }

clientId and clientSecret are optional: if the server supports dynamic client registration, Platica handles it.

Response

{
  "requiresOAuth": false,
  "serverInfo": {
    "name": "linear-mcp",
    "version": "1.4.0",
    "protocolVersion": "2025-06-18"
  },
  "transport": "streamable-http",
  "count": 2,
  "tools": [
    {
      "name": "create_issue",
      "description": "Create a new issue in Linear",
      "inputSchema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "teamId": { "type": "string" }
        },
        "required": ["title", "teamId"]
      }
    },
    {
      "name": "search_issues",
      "description": "Search issues by text query",
      "inputSchema": {
        "type": "object",
        "properties": { "query": { "type": "string" } }
      }
    }
  ]
}

The name values here are the server's original names, and they are what you pass as tools when connecting and syncing.

With auth.type: "oauth2" the response comes back as requiresOAuth: true with tools: []: discovery is only possible after authorizing.

Errors

Status	Cause
`400`	Invalid URL, or a missing `auth` field
`502`	Could not reach the MCP server, or the server failed to list its tools

List MCP Servers

GET https://api.platica.mx/v1/tools/mcp

Response

{
  "count": 1,
  "servers": [
    {
      "id": "QZPHpckDPC58JIVLQA3Z",
      "name": "Linear",
      "description": "Team issue tracking",
      "url": "https://mcp.linear.app/mcp",
      "transport": "streamable-http",
      "slug": "a1b2c3",
      "authType": "bearer",
      "status": "connected",
      "lastError": null,
      "serverInfo": { "name": "linear-mcp", "version": "1.4.0" },
      "discoveredToolsCount": 12,
      "installedToolsCount": 2,
      "customHeaderNames": [],
      "lastSyncAt": "2026-07-14T18:02:11.410Z",
      "createdAt": "2026-07-14T18:02:11.410Z",
      "updatedAt": "2026-07-14T18:02:11.410Z"
    }
  ]
}

Field	Type	Description
`status`	string	`connected`, `pending_auth` (OAuth not finished), `needs_reauth` (token expired) or `error`.
`lastError`	string \| null	Reason for the last failure when `status` is `error`.
`slug`	string \| null	Suffix Platica appends to each tool name to avoid clashes between servers.
`discoveredToolsCount`	number	Tools the server exposes.
`installedToolsCount`	number	How many of them are in the workspace catalog.
`customHeaderNames`	string[]	Names of custom headers. Values are never returned.

Connect MCP Server

Saves the server and installs its tools into the workspace catalog.

POST https://api.platica.mx/v1/tools/mcp

Request Body

{
  "name": "Linear",
  "description": "Team issue tracking",
  "url": "https://mcp.linear.app/mcp",
  "auth": {
    "type": "bearer",
    "token": "lin_api_xxx"
  },
  "tools": ["create_issue", "search_issues"]
}

Parameter	Type	Description	Required	Default
`name`	string	Display name inside Platica (≤ 120 characters)	✓	—
`url`	string	MCP server URL	✓	—
`description`	string	Internal note (≤ 500 characters)	—	`""`
`auth`	object	Same as preview	—	`{ "type": "none" }`
`headers`	object	Extra handshake headers	—	—
`tools`	string[]	Original names of the tools to install	—	all

If you omit tools, Platica asks the server and installs everything it exposes.

Response

{
  "status": "success",
  "message": "MCP server connected successfully",
  "data": {
    "mcpId": "QZPHpckDPC58JIVLQA3Z",
    "slug": "a1b2c3",
    "installedToolIds": ["8fK2mQpLxT4vNbRc", "Lm9RtWq3ZxYvBn2P"],
    "installedToolNames": ["create_issue", "search_issues"],
    "requiresOAuth": false
  }
}

installedToolIds are catalog toolIds: use them directly in POST /v1/agents/{agentId}/tools .

Advertencia

With auth.type: "oauth2" the server is saved with status: "pending_auth" and the response includes authorizeUrl. Open that URL in a browser to authorize, then call POST /v1/tools/mcp/{mcpId}/refresh to discover the tools. If OAuth could not start automatically, use Start OAuth .

Errors

Status	Cause
`400`	Missing `name` or `url`, or the URL is invalid
`502`	Could not reach the MCP server

Get MCP Server

Same as a list item, plus the detail of the tools it exposes and which ones are installed.

GET https://api.platica.mx/v1/tools/mcp/{mcpId}

URL parameters

Parameter	Type	Description	Required
`mcpId`	string	MCP server identifier	✓

Response

{
  "id": "QZPHpckDPC58JIVLQA3Z",
  "name": "Linear",
  "url": "https://mcp.linear.app/mcp",
  "transport": "streamable-http",
  "slug": "a1b2c3",
  "authType": "bearer",
  "status": "connected",
  "lastError": null,
  "discoveredToolsCount": 2,
  "installedToolsCount": 1,
  "customHeaderNames": [],
  "lastSyncAt": "2026-07-14T18:02:11.410Z",
  "discoveredTools": [
    {
      "name": "create_issue",
      "description": "Create a new issue in Linear",
      "inputSchema": { "type": "object", "properties": {} },
      "installed": true,
      "lastSeenAt": "2026-07-14T18:02:11.410Z"
    },
    {
      "name": "search_issues",
      "description": "Search issues by text query",
      "inputSchema": { "type": "object", "properties": {} },
      "installed": false,
      "lastSeenAt": "2026-07-14T18:02:11.410Z"
    }
  ],
  "installedTools": [
    {
      "id": "8fK2mQpLxT4vNbRc",
      "name": "mcp_create_issue_a1b2c3",
      "mcpToolName": "create_issue"
    }
  ]
}

discoveredTools is what the server offers; installedTools is what exists in the workspace catalog, with each one's toolId.

Errors

Status	Cause
`404`	The MCP server does not exist in the workspace

Start OAuth

Starts or restarts authorization for a server created with auth.type: "oauth2".

POST https://api.platica.mx/v1/tools/mcp/{mcpId}/oauth/start

Request Body

{
  "scope": "read write"
}

scope, clientId, and clientSecret are optional. The configuration saved when the server was connected is normally reused.

Response

{
  "status": "success",
  "message": "MCP OAuth authorization started",
  "data": {
    "mcpId": "QZPHpckDPC58JIVLQA3Z",
    "authorizeUrl": "https://provider.example.com/oauth/authorize?...",
    "state": "workspace.mcp.nonce"
  }
}

Open authorizeUrl in a browser. The callback stores encrypted tokens; then use Refresh MCP Server .

Errors

Status	Cause
`400`	The server does not use OAuth, or it requires its own `clientId`
`404`	The MCP server does not exist
`502`	Could not discover or contact the authorization server

Refresh MCP Server

Asks the server again what tools it exposes and updates the schemas of the ones already installed. Use it when the server changed its tools, or after completing an OAuth flow.

POST https://api.platica.mx/v1/tools/mcp/{mcpId}/refresh

URL parameters

Parameter	Type	Description	Required
`mcpId`	string	MCP server identifier	✓

Response

{
  "status": "success",
  "message": "MCP server refreshed successfully",
  "data": {
    "id": "QZPHpckDPC58JIVLQA3Z",
    "name": "Linear",
    "status": "connected",
    "discoveredToolsCount": 14,
    "installedToolsCount": 2,
    "discoveredTools": [],
    "installedTools": []
  }
}

data has the same shape as get server , already refreshed.

Refreshing does not install new tools: anything that shows up for the first time arrives with installed: false until you add it via /tools/sync.

Errors

Status	Cause
`401`	The server uses OAuth and authorization has not been completed
`404`	The MCP server does not exist in the workspace
`502`	Could not reach the server. Its `status` becomes `error` with the reason in `lastError`

Sync Installed Tools

Defines exactly which of the server's tools stay installed in the catalog.

POST https://api.platica.mx/v1/tools/mcp/{mcpId}/tools/sync

URL parameters

Parameter	Type	Description	Required
`mcpId`	string	MCP server identifier	✓

Request Body

{
  "tools": ["create_issue", "search_issues", "list_teams"]
}

Parameter	Type	Description	Required
`tools`	string[]	The complete list of original names that should remain installed	✓

Advertencia

This is a replacement, not an addition. Tools missing from the list are removed from the catalog and disconnected from every agent that had them. To add one without losing the rest, send the current list plus the new name.

Response

{
  "status": "success",
  "message": "MCP tools updated successfully",
  "data": {
    "mcpId": "QZPHpckDPC58JIVLQA3Z",
    "installedCount": 3,
    "installedToolIds": ["tool-1", "tool-2", "tool-3"],
    "installedToolNames": ["create_issue", "search_issues", "list_teams"],
    "removedToolCount": 1,
    "removedAgentConnections": 2
  }
}

Names that are not among the discovered tools are silently ignored: if a server stopped exposing a tool, it cannot be installed. Refresh first to see the current list.

Errors

Status	Cause
`404`	The MCP server does not exist in the workspace

Delete MCP Server

DELETE https://api.platica.mx/v1/tools/mcp/{mcpId}

URL parameters

Parameter	Type	Description	Required
`mcpId`	string	MCP server identifier	✓

Response

{
  "status": "success",
  "message": "MCP server deleted successfully",
  "data": {
    "mcpId": "QZPHpckDPC58JIVLQA3Z",
    "removedTools": 2,
    "removedAgentConnections": 3
  }
}

This removes the server, its credentials, all of its catalog tools, and any connections those tools had with any agent. It cannot be undone.

Errors

Status	Cause
`404`	The MCP server does not exist in the workspace

Previous Agent Tools Next Custom APIs