Conectar mediante MCP

MCP remoto: conectar por URL ​

Una instancia sirve el Model Context Protocol mediante Streamable HTTP en https://YOUR-INSTANCE/mcp. Lo tienen tanto una instancia alojada (por ejemplo en Sliplane) como un obop serve local; no hay nada que activar.

• Autenticación: un inicio de sesión en el navegador (OAuth, véase abajo) para Claude Desktop, claude.ai y Claude Code, o Authorization: Bearer <token> en cada petición con un token de agente. En ambos casos el token se comprueba como en REST. Un token ausente o inválido recibe 401 con WWW-Authenticate: Bearer resource_metadata="https://YOUR-INSTANCE/.well-known/oauth-protected-resource/mcp", como pide la especificación de autorización de MCP; ese documento nombra el servidor de autorización de la instancia (/.well-known/oauth-authorization-server). Un token emitido por el inicio de sesión solo vale para /mcp, no para /api.
• Revisiones del protocolo: 2025-11-25, 2025-06-18 y 2025-03-26, negociadas en initialize. La revisión más reciente, 2026-07-28, no tiene estado y funciona de otra manera; obop todavía no la implementa. Un cliente que admite ambas vuelve a initialize cuando recibe un 400 simple, que es lo que envía obop ante una cabecera de versión no admitida.
• Sesiones: initialize devuelve un Mcp-Session-Id; envíalo en todas las peticiones posteriores. La sesión conserva la bóveda de enmascarado, de modo que un token de máscara como NAME_1 significa lo mismo en todas las llamadas de la sesión y puedes enviarlo de vuelta. Una sesión distinta inicia una bóveda nueva. DELETE /mcp termina una sesión; una sesión desconocida o caducada responde 404 y el cliente vuelve a empezar con initialize. Una sesión pertenece al token que la abrió y caduca tras dos horas sin ninguna petición.
• Las respuestas son JSON simple. No hay un flujo SSE del servidor al cliente (GET /mcp responde 405), y los lotes JSON-RPC solo se aceptan en 2025-03-26, la única revisión que los tiene.
• Límites: cuerpos de petición de hasta 1 MiB (413), 600 peticiones por minuto y token (429 con Retry-After, ajustable con OBOP_MCP_RATE_PER_MINUTE), 25 sesiones abiertas por token.
• Navegadores: una petición con cabecera Origin se rechaza con 403 salvo que el origen sea la URL pública de la propia instancia (OBOP_PUBLIC_URL), el mismo origen en un host de loopback, o esté incluido en OBOP_ALLOWED_ORIGINS (separado por comas). Esto protege las instancias locales frente al DNS rebinding. Los clientes que no son navegadores no envían Origin. Detrás de un proxy, define OBOP_PUBLIC_URL (por ejemplo https://acme.example.com) para que los documentos de descubrimiento indiquen la dirección pública.

Conectar con un inicio de sesión en el navegador (OAuth) ​

Claude Desktop, claude.ai y Claude Code pueden conectarse a una instancia sin pegar un token. En la aplicación añade un conector personalizado (custom connector) con la dirección https://YOUR-INSTANCE/mcp (Claude Code: claude mcp add --transport http obop https://YOUR-INSTANCE/mcp, luego /mcp y elige autenticar). La aplicación encuentra sola el inicio de sesión y abre en el navegador una página de tu instancia. Allí:

1. inicias sesión con tu cuenta de obop e introduces tu código de dos pasos si la cuenta lo tiene (una clave de acceso también sirve, como segundo paso o sola si lo permitiste en Seguridad);
2. ves qué aplicación lo solicita y a qué dirección volverá el navegador;
3. marcas los grupos de permisos que cedes, eliges cuánto dura el acceso (1, 7, 30 o 90 días) y pulsas Permitir.

Qué significa:

• La aplicación solo puede restringirte. Se te ofrecen los grupos que tú tienes; la aplicación actúa como tú con los que marques, nunca con más (los tokens de agente funcionan igual). Sus acciones se registran como las de tu agente.
• Las aprobaciones siguen necesitando a una persona. Un paso que requiere aprobación espera en obop a un humano; la aplicación no puede aprobar sus propias propuestas.
• Tokens de corta duración. La aplicación recibe un token de acceso que dura una hora y un token de renovación que se usa una vez y se sustituye cada vez. Si un token de renovación se usa dos veces, termina toda la conexión. Un token de acceso de este inicio de sesión vale solo para /mcp.
• Mantienes el control. En Personalizar, Seguridad, Aplicaciones conectadas aparece cada conexión con sus grupos y su fecha de fin; Revocar la termina al instante. Conectar, rechazar, revocar y un token usado dos veces figuran en el registro de seguridad.
• No se confía en nada de antemano. Cualquier aplicación puede registrarse sola, así que la página muestra el nombre que eligió y la dirección de retorno, y dice que obop no puede comprobar quién la gestiona. Las direcciones de retorno deben ser https (o http en localhost, 127.0.0.1 o [::1]), los registros están limitados y los que no se usan caducan.

Protocolo, para autores de clientes: metadatos según RFC 9728 y RFC 8414, registro dinámico de clientes (RFC 7591, clientes públicos), código de autorización con PKCE S256 (obligatorio), el parámetro resource (RFC 8707, debe ser la dirección /mcp de la instancia), rotación de tokens de renovación con detección de reutilización, revocación (RFC 7009) y el parámetro iss en la redirección (RFC 9207). Endpoints: /oauth/register, /oauth/authorize, /oauth/token, /oauth/revoke. Una redirección loopback (http://127.0.0.1:PUERTO/...) puede usar cualquier puerto (RFC 8252); cualquier otra debe coincidir exactamente. Una instancia detrás de un proxy necesita OBOP_PUBLIC_URL para que las direcciones de estos documentos sean las públicas. Lo hemos construido según la especificación y probado con un cliente propio en pruebas automatizadas; todavía no hemos conectado las aplicaciones reales de Claude.

Herramientas ​

tools/list muestra una herramienta por cada comando que el token puede usar, con el nombre <model>__<command>: party__search, lead__create, invoice__post. Cada una tiene un inputSchema en JSON Schema generado a partir del modelo: los campos de dinero y numéricos son enteros, las fechas son format: date, los campos de selección son un enum con sus opciones, un campo de referencia es una cadena que nombra su modelo de destino, y los campos obligatorios están en required. list y search aceptan filter, order, limit y offset; get, delete y las acciones aceptan un id. Las anotaciones marcan las lecturas (readOnlyHint) y el borrado (destructiveHint). Una herramienta adicional de solo lectura, obop__meta, devuelve lo mismo que GET /api/meta: empieza por ahí. Una herramienta que el token no puede usar no aparece en la lista y responde como una herramienta que no existe.

Los resultados tienen structuredContent y el mismo JSON como texto:

{ "status": "ok", "value": [{ "id": "...", "name": "NAME_1" }], "denied": ["party.tax_id"] }

• Un paso que necesita a una persona (todo borrado, contabilizar una factura) no se ejecuta para un agente. El resultado es un resultado normal con "status": "approval_required", un plan_id y una instrucción para consultar a una persona, que lo aprueba en el back office o con POST /api/approve/<plan_id>. Consulta El ciclo de aprobación.
• Una entrada rechazada (un valor incorrecto, un campo que falta) es un error de herramienta: isError: true y el mensaje del servidor en structuredContent.error.
• initialize también devuelve instructions, un texto breve que indica al modelo cómo usar la instancia.

tools/list se pagina con un cursor solo cuando un token ve más de 200 herramientas. La lista no anuncia cambios (listChanged es false): tras instalar un módulo, inicia una sesión nueva.

Compruébalo con curl ​

export OBOP_URL=https://YOUR-INSTANCE
export OBOP_TOKEN=obop_...
curl -si -X POST "$OBOP_URL/mcp" \
  -H "Authorization: Bearer $OBOP_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Copia la cabecera mcp-session-id de la respuesta, y después envía {"jsonrpc":"2.0","method":"notifications/initialized"} (respuesta 202) y {"jsonrpc":"2.0","id":2,"method":"tools/list"}, ambos con -H "Mcp-Session-Id: <id>".

Configuración de clientes remotos ​

Sustituye https://YOUR-INSTANCE/mcp y guarda el token en una variable de entorno o en un almacén de secretos. Los formatos siguientes se tomaron de la documentación de cada cliente el 2026-10-17. Solo ejecutamos obop contra el cliente de línea de comandos MCP Inspector (vp dlx @modelcontextprotocol/inspector --cli URL --transport http --header "Authorization: Bearer ..." --method tools/list) y contra nuestras propias pruebas de Playwright. No iniciamos los demás clientes, así que cada fragmento está documentado, no probado.

Claude Code ​

claude mcp add --transport http obop https://YOUR-INSTANCE/mcp \
  --header "Authorization: Bearer $OBOP_TOKEN"

Añade --scope project para escribir un .mcp.json compartido o --scope user para usarlo en todos los proyectos. En un archivo compartido, lee el token del entorno para que no se suba al repositorio:

{
  "mcpServers": {
    "obop": {
      "type": "http",
      "url": "https://YOUR-INSTANCE/mcp",
      "headers": { "Authorization": "Bearer ${OBOP_TOKEN}" }
    }
  }
}

Si el servidor rechaza la cabecera, Claude Code informa de un fallo de conexión en lugar de iniciar OAuth. Compruébalo con /mcp.

Claude Desktop y claude.ai ​

Las aplicaciones añaden servidores remotos como conectores personalizados (Settings, Connectors, Add custom connector) y los autentican con OAuth. Introduce https://YOUR-INSTANCE/mcp y sigue el inicio de sesión en el navegador descrito arriba; no se pega ningún token. Para claude.ai la instancia debe ser accesible desde internet por https, porque las peticiones las hacen los servidores de Anthropic. La configuración stdio más abajo funciona en Claude Desktop con un binario local. Un puente como el paquete de la comunidad mcp-remote puede añadir una cabecera a un servidor remoto para clientes que solo hablan stdio; no lo hemos probado con obop.

Cursor ​

.cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (todos los proyectos):

{
  "mcpServers": {
    "obop": {
      "url": "https://YOUR-INSTANCE/mcp",
      "headers": { "Authorization": "Bearer ${env:OBOP_TOKEN}" }
    }
  }
}

VS Code ​

.vscode/mcp.json. La clave de nivel superior es servers, y una entrada pide el token para que no se escriba en disco:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "obop-token",
      "description": "obop agent token",
      "password": true
    }
  ],
  "servers": {
    "obop": {
      "type": "http",
      "url": "https://YOUR-INSTANCE/mcp",
      "headers": { "Authorization": "Bearer ${input:obop-token}" }
    }
  }
}

La documentación de VS Code no mostraba un ejemplo completo con cabeceras y una entrada, así que este fragmento se ha montado a partir de sus tablas de campos.

Windsurf ​

La documentación de Windsurf ahora está en el sitio de Devin Desktop. Indica ~/.config/devin/mcp_config.json (macOS y Linux) y %APPDATA%\devin\mcp_config.json (Windows); las instalaciones antiguas de Windsurf usaban ~/.codeium/windsurf/mcp_config.json. Comprueba cuál lee tu versión. Los servidores remotos usan serverUrl (o url) y headers, y ${env:NAME} se expande:

{
  "mcpServers": {
    "obop": {
      "serverUrl": "https://YOUR-INSTANCE/mcp",
      "headers": { "Authorization": "Bearer ${env:OBOP_TOKEN}" }
    }
  }
}

Codex CLI ​

En ~/.codex/config.toml. bearer_token_env_var nombra la variable de entorno que contiene el token; Codex lo envía como bearer token en Authorization:

[mcp_servers.obop]
url = "https://YOUR-INSTANCE/mcp"
bearer_token_env_var = "OBOP_TOKEN"

codex mcp add documenta --url solo con opciones de OAuth, así que usa el archivo para un bearer token.

Gemini CLI ​

La documentación que leímos indica que Gemini CLI fue sustituido por Antigravity CLI el 2026-06-18; consulta la página de la herramienta que uses. El formato de Gemini CLI es httpUrl para Streamable HTTP (url es para el transporte SSE anterior), en ~/.gemini/settings.json:

{
  "mcpServers": {
    "obop": {
      "httpUrl": "https://YOUR-INSTANCE/mcp",
      "headers": { "Authorization": "Bearer your-agent-token" }
    }
  }
}

o gemini mcp add --transport http --header "Authorization: Bearer $OBOP_TOKEN" obop https://YOUR-INSTANCE/mcp. No pudimos confirmar que este archivo expanda variables de entorno en headers, por lo que aquí el token está escrito en claro.

Descubrimiento ​

Una instancia publica lo siguiente sin necesidad de token:

La tarjeta del servidor es una extensión de la especificación MCP que aún se está desarrollando (SEP-2127, mantenida en un repositorio de incubación), por lo que su forma puede cambiar; el archivo lo indica en su $comment. También incluye los campos simples serverInfo, transport, endpoint y capabilities de un borrador anterior, para los analizadores que los buscan.

MCP sobre stdio (binario local) ​

Úsalo cuando el cliente solo pueda iniciar un programa local, o cuando ejecutes obop en la misma máquina. El servidor remoto descrito arriba no necesita nada de esto.

Cómo funciona ​

obop mcp es un servidor MCP que habla JSON-RPC por la entrada y la salida estándar. Un cliente MCP lo inicia como proceso hijo. Este servidor:

• abre él mismo la base de datos de la instancia, por lo que debe ejecutarse en una máquina que pueda llegar a la base de datos (archivo SQLite o URL de PostgreSQL);
• identifica al agente mediante un token de agente;
• lista las mismas herramientas, con los mismos esquemas, que el servidor remoto (ambos transportes usan un único camino de código): una herramienta por cada comando que ese token puede usar, con el nombre <model>__<command>. El doble guion bajo ocupa el lugar de la barra en la ruta REST;
• responde a tools/call a través del mismo despachador que REST, de modo que se aplican el enmascarado y las aprobaciones. Los tokens de máscara son estables mientras el proceso siga en ejecución.

Antes de empezar ​

1. La base de datos de una instancia en marcha y el binario obop en la máquina que ejecuta el cliente MCP (o usa su ruta absoluta).
2. Un token de agente con los scopes que quieras.
3. La dirección de la base de datos, como OBOP_DATABASE_URL o --db. El valor por defecto es sqlite://obop.db en el directorio actual, así que indica una ruta absoluta: sqlite:///home/me/obop.db.

El comando que ejecuta cada cliente es:

obop mcp --db sqlite:///home/me/obop.db --token obop_...

Si faltan las opciones, lee OBOP_TOKEN y OBOP_DATABASE_URL del entorno. Es preferible usar el entorno: así el token no aparece en la lista de procesos.

Compruébalo primero a mano. Esto envía una petición initialize y otra tools/list e imprime las respuestas:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | OBOP_TOKEN=obop_... OBOP_DATABASE_URL=sqlite:///home/me/obop.db obop mcp

El servidor responde con la revisión que pide el cliente si es una de 2025-11-25, 2025-06-18 y 2025-03-26, y admite initialize, ping, tools/list y tools/call. Los argumentos de una herramienta son el mismo JSON que el cuerpo REST.

Los fragmentos siguientes usan /usr/local/bin/obop y un token de ejemplo. Sustituye ambos. Los formatos se comprobaron con la documentación de cada cliente el 2026-10-16; lo que no se pudo confirmar está indicado.

Claude Desktop (stdio) ​

Abre Settings, luego Developer y después Edit Config. El archivo es ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y %APPDATA%\Claude\claude_desktop_config.json en Windows. Añade:

{
  "mcpServers": {
    "obop": {
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "obop_your_agent_token",
        "OBOP_DATABASE_URL": "sqlite:///Users/me/obop.db"
      }
    }
  }
}

Cierra y reinicia Claude Desktop. Claude pide tu aprobación antes de usar una herramienta.

Claude Code (stdio) ​

Usa la línea de comandos. Todo lo que va después de -- es el comando del servidor:

claude mcp add --transport stdio \
  --env OBOP_TOKEN=obop_your_agent_token \
  --env OBOP_DATABASE_URL=sqlite:///home/me/obop.db \
  obop -- /usr/local/bin/obop mcp

Coloca al menos otra opción (aquí --transport stdio) entre el último --env y el nombre del servidor. Añade --scope project para escribir en su lugar un .mcp.json compartido, o --scope user para usarlo en todos los proyectos. Un archivo de proyecto tiene este aspecto; la forma ${...} lee el valor de tu entorno para que el token no se suba al repositorio:

{
  "mcpServers": {
    "obop": {
      "type": "stdio",
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "${OBOP_TOKEN}",
        "OBOP_DATABASE_URL": "sqlite:///home/me/obop.db"
      }
    }
  }
}

Compruébalo con claude mcp get obop o con /mcp dentro de Claude Code.

Cursor (stdio) ​

Crea .cursor/mcp.json en un proyecto, o ~/.cursor/mcp.json para todos los proyectos:

{
  "mcpServers": {
    "obop": {
      "type": "stdio",
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "${env:OBOP_TOKEN}",
        "OBOP_DATABASE_URL": "sqlite:///Users/me/obop.db"
      }
    }
  }
}

Los ejemplos propios de Cursor omiten type en los servidores stdio; su tabla de campos sí lo incluye. ${env:NAME} lee del entorno en el que se inició Cursor.

VS Code (stdio) ​

Crea .vscode/mcp.json. La clave de nivel superior de VS Code es servers, no mcpServers, y puede pedir el token para que nunca se escriba en disco:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "obop-token",
      "description": "obop agent token",
      "password": true
    }
  ],
  "servers": {
    "obop": {
      "type": "stdio",
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "${input:obop-token}",
        "OBOP_DATABASE_URL": "sqlite:///Users/me/obop.db"
      }
    }
  }
}

El comando guiado MCP: Add Server de VS Code puede sugerir en su lugar un .mcp.json portable con el formato mcpServers; según su documentación, se aceptan ambos.

Windsurf (stdio) ​

La documentación de Windsurf se ha trasladado al sitio de Devin Desktop y describe el archivo como mcp_config.json. No pudimos confirmar la ubicación actual del archivo para el propio Windsurf. Históricamente, Windsurf usaba ~/.codeium/windsurf/mcp_config.json; la página de Devin Desktop indica ~/.config/devin/mcp_config.json (macOS y Linux) y %APPDATA%\devin\mcp_config.json (Windows). Comprueba la ubicación en los ajustes de tu versión. El formato es la misma estructura mcpServers:

{
  "mcpServers": {
    "obop": {
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "${env:OBOP_TOKEN}",
        "OBOP_DATABASE_URL": "sqlite:///Users/me/obop.db"
      }
    }
  }
}

Codex CLI (stdio) ​

Añade una tabla a ~/.codex/config.toml (o a .codex/config.toml en un proyecto de confianza), o ejecuta codex mcp add:

[mcp_servers.obop]
command = "/usr/local/bin/obop"
args = ["mcp"]
env_vars = ["OBOP_TOKEN"]

[mcp_servers.obop.env]
OBOP_DATABASE_URL = "sqlite:///home/me/obop.db"

env_vars reenvía OBOP_TOKEN desde tu shell en lugar de escribirlo en el archivo.

Gemini CLI (stdio) ​

Añade a ~/.gemini/settings.json:

{
  "mcpServers": {
    "obop": {
      "command": "/usr/local/bin/obop",
      "args": ["mcp"],
      "env": {
        "OBOP_TOKEN": "$OBOP_TOKEN",
        "OBOP_DATABASE_URL": "sqlite:///home/me/obop.db"
      }
    }
  }
}

La documentación de Gemini CLI indica que en 2026 fue sustituido por otra herramienta, así que consulta esa página para tu versión. No hemos probado obop con él.

Cualquier otro cliente MCP ​

obop es un servidor stdio sencillo. Sea cual sea el aspecto del archivo del cliente, necesita un command (obop), unos args (["mcp"]) y dos variables de entorno. Si el cliente solo admite servidores remotos, usa el servidor remoto descrito arriba.

Qué ve el agente ​

Tras conectar, pide al agente que liste sus herramientas. Deberías ver solo los comandos que permiten sus scopes, con una nota en los que requieren aprobación. Prueba primero una lectura, por ejemplo "Lista las tres oportunidades más recientes", y después consulta El ciclo de aprobación.

Si el cliente no muestra herramientas o da un error, ve a Solución de problemas.

Cada modelo que el agente puede crear tiene también una herramienta <model>__bulk_create: hasta 1000 filas en una llamada (rows o texto csv), todo o nada por defecto, mode: "partial" conserva las filas correctas y lista las incorrectas, dry_run: true comprueba primero y una idempotency_key hace seguro un reintento. El enmascaramiento, el alcance y la aprobación son los de create.

Un agente cuyo propietario es administrador ve además las herramientas user_account (user_account__list, __get, __add, __set_groups, __offboard, __disable, __enable). Las que cambian una cuenta devuelven siempre approval_required: un administrador aprueba el plan, que se ejecuta como la cuenta actual de ese administrador. __add exige una contraseña elegida por una persona; el servidor nunca entrega a un agente una contraseña generada.

Verificado y no verificado ​