Servidores MCP

MCP es un protocolo abierto que permite que un servicio exponga herramientas a un modelo. Conectando un servidor MCP al workspace, todas sus herramientas quedan disponibles en el catálogo para dárselas a cualquier agente.

El flujo normal tiene tres pasos:

POST /v1/tools/mcp/preview        → ves qué expone el servidor
POST /v1/tools/mcp                → lo conectas e instalas las que quieras
POST /v1/agents/{agentId}/tools   → se las das a un agente

Advertencia

Las credenciales del servidor (tokens, headers de autenticación, tokens OAuth) se guardan cifradas y nunca se devuelven en ninguna respuesta. Sólo verás el authType y los nombres de los headers personalizados.

Nota

Por seguridad, los servidores MCP sólo pueden resolver a direcciones públicas. Se bloquean localhost, redes privadas, link-local, metadata de nube y redirecciones hacia esos destinos.

Explorar Servidor MCP

Se conecta al servidor, negocia el transporte y lista sus herramientas. No guarda nada — es la llamada previa para decidir qué instalar.

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

Cuerpo de la solicitud

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

Parámetro	Tipo	Descripción	Requerido	Default
`url`	string	URL del servidor MCP. Debe ser `https`	✓	—
`auth`	objeto	Autenticación del servidor. Ver abajo	—	`{ "type": "none" }`
`headers`	objeto	Headers extra para el handshake, como pares `nombre: valor`	—	—

Sin autenticación

{ "type": "none" }

Bearer token

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

API key en un header

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

headerPrefix es el texto que va antes del token; déjalo vacío si el header lleva sólo el valor.

OAuth 2

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

Los campos clientId y clientSecret son opcionales: si el servidor soporta registro dinámico de cliente, Platica lo hace solo.

Respuesta

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

Los name de esta respuesta son los nombres originales del servidor, y son los que se pasan como tools al conectar y al sincronizar.

Con auth.type: "oauth2" la respuesta llega con requiresOAuth: true y tools: []: el descubrimiento sólo es posible después de autorizar.

Errores

Status	Causa
`400`	La URL no es válida o falta un campo de `auth`
`502`	No se pudo conectar al servidor MCP, o el servidor falló al listar sus herramientas

Listar Servidores MCP

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

Respuesta

{
  "count": 1,
  "servers": [
    {
      "id": "QZPHpckDPC58JIVLQA3Z",
      "name": "Linear",
      "description": "Gestión de issues del equipo",
      "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"
    }
  ]
}

Campo	Tipo	Descripción
`status`	string	`connected`, `pending_auth` (falta completar OAuth), `needs_reauth` (el token expiró) o `error`.
`lastError`	string \| null	Motivo del último fallo cuando `status` es `error`.
`slug`	string \| null	Sufijo que Platica añade al nombre de cada herramienta para evitar choques entre servidores.
`discoveredToolsCount`	number	Herramientas que expone el servidor.
`installedToolsCount`	number	Cuántas de ellas están en el catálogo del workspace.
`customHeaderNames`	string[]	Nombres de los headers personalizados. Los valores nunca se devuelven.

Conectar Servidor MCP

Guarda el servidor e instala sus herramientas en el catálogo del workspace.

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

Cuerpo de la solicitud

{
  "name": "Linear",
  "description": "Gestión de issues del equipo",
  "url": "https://mcp.linear.app/mcp",
  "auth": {
    "type": "bearer",
    "token": "lin_api_xxx"
  },
  "tools": ["create_issue", "search_issues"]
}

Parámetro	Tipo	Descripción	Requerido	Default
`name`	string	Nombre visible del servidor dentro de Platica (≤ 120 caracteres)	✓	—
`url`	string	URL del servidor MCP	✓	—
`description`	string	Nota interna (≤ 500 caracteres)	—	`""`
`auth`	objeto	Igual que en explorar	—	`{ "type": "none" }`
`headers`	objeto	Headers extra para el handshake	—	—
`tools`	string[]	Nombres originales de las herramientas a instalar	—	todas

Si omites tools, Platica consulta al servidor y instala todo lo que exponga.

Respuesta

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

Los installedToolIds son los toolId del catálogo: úsalos directamente en POST /v1/agents/{agentId}/tools .

Advertencia

Con auth.type: "oauth2" el servidor se guarda con status: "pending_auth" y la respuesta incluye authorizeUrl. Abre esa URL en un navegador para autorizar; después llama a POST /v1/tools/mcp/{mcpId}/refresh para descubrir las herramientas. Si no se pudo iniciar OAuth automáticamente, usa el endpoint Iniciar OAuth .

Errores

Status	Causa
`400`	Falta `name` o `url`, o la URL no es válida
`502`	No se pudo conectar al servidor MCP

Obtener Servidor MCP

Igual que un elemento de la lista, más el detalle de las herramientas que expone y cuáles están instaladas.

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

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`mcpId`	string	Identificador del servidor MCP	✓

Respuesta

{
  "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 es lo que el servidor ofrece; installedTools es lo que existe en el catálogo del workspace, con el toolId de cada uno.

Errores

Status	Causa
`404`	El servidor MCP no existe en el workspace

Iniciar OAuth

Inicia o reinicia la autorización de un servidor creado con auth.type: "oauth2".

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

Cuerpo de la solicitud

{
  "scope": "read write"
}

scope, clientId y clientSecret son opcionales. Normalmente se reutiliza la configuración guardada al conectar el servidor.

Respuesta

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

Abre authorizeUrl en un navegador. El callback guarda los tokens cifrados; después usa Refrescar Servidor MCP .

Errores

Status	Causa
`400`	El servidor no usa OAuth o necesita un `clientId` propio
`404`	El servidor MCP no existe
`502`	No se pudo descubrir o contactar al servidor de autorización

Refrescar Servidor MCP

Vuelve a preguntarle al servidor qué herramientas expone y actualiza los esquemas de las que ya están instaladas. Úsalo cuando el servidor haya cambiado sus herramientas, o después de completar un flujo OAuth.

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

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`mcpId`	string	Identificador del servidor MCP	✓

Respuesta

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

data tiene la misma forma que obtener servidor , ya con los datos actualizados.

Refrescar no instala herramientas nuevas: las que aparezcan por primera vez llegan con installed: false hasta que las agregues con /tools/sync.

Errores

Status	Causa
`401`	El servidor usa OAuth y falta completar la autorización
`404`	El servidor MCP no existe en el workspace
`502`	No se pudo conectar al servidor. Su `status` queda en `error` con el motivo en `lastError`

Sincronizar Herramientas Instaladas

Define exactamente qué herramientas del servidor quedan instaladas en el catálogo.

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

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`mcpId`	string	Identificador del servidor MCP	✓

Cuerpo de la solicitud

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

Parámetro	Tipo	Descripción	Requerido
`tools`	string[]	Lista completa de nombres originales que deben quedar instalados	✓

Advertencia

Es un reemplazo, no un agregado. Las herramientas que no estén en la lista se eliminan del catálogo y se desconectan de todos los agentes que las tuvieran. Para agregar una sin perder las demás, manda la lista actual más la nueva.

Respuesta

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

Los nombres que no aparezcan entre los descubiertos se ignoran en silencio: si un servidor dejó de exponer una herramienta, no se puede instalar. Refresca primero para ver la lista vigente.

Errores

Status	Causa
`404`	El servidor MCP no existe en el workspace

Eliminar Servidor MCP

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

Parámetros de URL

Parámetro	Tipo	Descripción	Requerido
`mcpId`	string	Identificador del servidor MCP	✓

Respuesta

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

Se elimina el servidor, sus credenciales, todas sus herramientas del catálogo y las conexiones que esas herramientas tuvieran con cualquier agente. No es reversible.

Errores

Status	Causa
`404`	El servidor MCP no existe en el workspace

Anterior Herramientas de Agente Siguiente APIs Personalizadas