MCP: use OneType desde Claude Code, Cursor y otras herramientas de IA

OneType es un servidor MCP (Model Context Protocol, Streamable HTTP). Cualquier cliente MCP puede llamarlo con una clave de API: Claude Code, Cursor, Claude Desktop o sus propios agentes. Hay dos servidores:

Servidor	URL	Para	Herramientas
Workspace	`https://api.onetype.ai/v1/mcp`	Su equipo y sus propias automatizaciones: leer agentes y conversaciones, buscar en el conocimiento, preguntar a un agente y crear agentes	Herramientas de lectura: `list_agents`, `get_agent`, `list_conversations`, `get_conversation`, `list_messages`, `search_knowledge`, `ask_agent`. Herramientas de creación: véase Herramientas de creación
Docs de un agente (proporcionado por OneType)	`https://api.onetype.ai/v1/mcp/agents/YOUR_AGENT_ID`	Sus desarrolladores y clientes: las mismas respuestas con fuentes que su chat, dentro de su editor	`search_docs`, `ask_agent`

Estado: ambos servidores están Disponibles. Ambos requieren Premium: en Free, las conexiones MCP se rechazan con 422 PLAN_LIMIT.

1. Cree una clave

Servidor del workspace: en Developer › API keys, cree una clave restringida (rk_live_…) y marque solo los permisos que necesite:
- agents.read para list_agents y get_agent
- conversations.read para list_conversations, get_conversation y list_messages
- search.debug para search_knowledge
- conversations.write para ask_agent
- para una herramienta de creación, el permiso de la misma acción en la aplicación (por ejemplo agents.update para update_agent, knowledge.write para add_website)
Docs de un agente: en la página MCP , abra la tarjeta del agente y cree su clave. La clave tiene mcp.agent y se limita a ese único agente, así que no puede leer nada más de su workspace. Puede compartirla sin riesgo con los desarrolladores que usan sus docs.

Las claves se muestran una sola vez. Revocar una surte efecto en la siguiente solicitud.

2. Conecte su cliente

Claude Code

claude mcp add --transport http onetype https://api.onetype.ai/v1/mcp \
  --header "Authorization: Bearer rk_live_…"

Docs de un agente:

claude mcp add --transport http onetype-docs https://api.onetype.ai/v1/mcp/agents/YOUR_AGENT_ID \
  --header "Authorization: Bearer rk_live_…"

Cursor (.cursor/mcp.json), Claude Desktop y otros clientes que aceptan JSON:

{
  "mcpServers": {
    "onetype-docs": {
      "url": "https://api.onetype.ai/v1/mcp/agents/YOUR_AGENT_ID",
      "headers": { "Authorization": "Bearer rk_live_…" }
    }
  }
}

Developer › MCP muestra ambos fragmentos con su URL ya rellenada.

Después pregunte en su editor: «Using onetype-docs, how do I verify a webhook signature?» La respuesta llega con sus fuentes.

Qué hace cada herramienta

Herramienta	Servidor	Devuelve	Facturación
`list_agents`, `get_agent`	workspace	Agentes, tal como los devuelve la REST API	gratis
`list_conversations`, `get_conversation`, `list_messages`	workspace	Conversaciones y sus mensajes	gratis
`search_knowledge`	workspace	Los pasajes que mejor coinciden del conocimiento de un agente, con fuentes	gratis
`search_docs`	un agente	Los pasajes que mejor coinciden del conocimiento de ese agente, con fuentes	gratis
`ask_agent`	ambos	Una respuesta completa del agente, con citas	una respuesta, como una respuesta de chat

Los pasajes, mensajes y respuestas se marcan como contenido no fiable para el modelo que llama, de modo que el texto de sus documentos no puede dar instrucciones a la IA del cliente: en ambos servidores, todo campo que escribieron sus documentos, sus visitantes o un modelo (el header y el text de un pasaje, el text de un mensaje, el title de una fuente, el name y las instructions de un agente) llega como un objeto { "untrusted_text": "…" }, nunca como una cadena suelta. Lea la cadena en untrusted_text. Cada llamada queda registrada en su registro de auditoría (mcp.tool.called). El resultado de una herramienta nunca inicia nada en el servidor.

Herramientas de creación

El servidor del workspace también crea y ejecuta agentes. Cada herramienta funciona como la misma acción en la aplicación: con los mismos permisos, límites del plan y registro de auditoría.

Grupo	Herramientas
Cuenta	`get_account`
Agentes	`list_models`, `create_agent`, `update_agent`, `publish_agent`, `take_agent_offline`, `resume_agent`, `delete_agent`
Conocimiento	`list_sources`, `get_source`, `add_website`, `add_pages`, `add_text`, `add_file`, `resync_source`, `remove_source`, `list_qna`, `add_qna`, `update_qna`, `delete_qna`
Chat y sitio	`set_allowed_domains`, `get_look`, `update_look`, `apply_look`, `set_bubble`, `get_install_snippet`, `test_agent` (se factura como una respuesta de chat)
Plantillas y enlaces	`list_templates`, `get_template`, `get_builder_prompt`, `get_checkout_link`, `get_connect_link`, `get_app_link`

Las llamadas destructivas esperan a una persona. Eliminar un agente, una fuente o una pregunta y respuesta, publicar un agente o ponerlo fuera de línea y, en un agente en vivo, publicar su aspecto, cambiar sus dominios permitidos o cambiar lo que se dice a los visitantes o lo que se recoge de ellos, responden needs_confirm con un enlace. Una persona con sesión iniciada en OneType lo aprueba en el navegador; la misma llamada con confirm establecido en el id indicado pasa entonces una vez, en un máximo de 10 minutos. El pago y la conexión de otras herramientas también se hacen en el navegador, mediante los enlaces que devuelven las herramientas. Los cambios están limitados a 60 por minuto, y create_agent a 10 por hora.

Para desarrolladores de otros clientes MCP

POST recibe un mensaje JSON-RPC. initialize responde con una cabecera Mcp-Session-Id ; envíela en las solicitudes posteriores.
Las versiones de protocolo admitidas son 2025-11-25 y 2025-06-18.
Métodos: ping, tools/list, tools/call. Las notificaciones responden 202. DELETE termina una sesión, y GET responde 405. Las sesiones terminan tras un día sin uso.
tools/list solo ofrece una herramienta cuando la clave tiene su permiso.

Errores

Respuesta	Significado	Solución
`401`	Clave ausente o revocada	Compruebe la `Authorization` (cabecera)
`403 ORIGIN_NOT_ALLOWED`	Llamada desde una página del navegador	Llámelo desde un servidor o un cliente de escritorio. Las claves nunca deben estar en un navegador
`403 AGENT_SCOPED_KEY`	La clave de un agente usada en el servidor del workspace	Use la URL del agente o una clave del workspace
`403 AGENT_OUT_OF_SCOPE`, `422 PLAN_LIMIT`	La clave no es de este agente, o el workspace está en Free	Use la clave de ese agente o suba a Premium
`400 SESSION_REQUIRED`, `PROTOCOL_VERSION_MISMATCH` · `404 SESSION_NOT_FOUND`	Gestión de sesión	Vuelva a ejecutar `initialize`
JSON-RPC `-32601` / `-32602`	Método desconocido, o herramienta desconocida o argumentos incorrectos	Llame a `tools/list` para ver qué puede usar esta clave
Un resultado con `isError: true`	Se rechazó la herramienta (p. ej., por falta de un permiso)	Su código y mensaje explican el motivo

Las personas también pueden conectarse con OAuth en lugar de una clave: claude.ai y Claude Desktop (un conector personalizado) y ChatGPT inician sesión mediante la pantalla de consentimiento de OneType. La página MCP de la aplicación tiene los pasos para cada herramienta.