Servidor MCP

Helmcode expone un servidor MCP remoto (Model Context Protocol) para que uses nuestras herramientas directamente dentro de agentes y editores compatibles con MCP — autenticado con la misma API key que ya usas para la API REST.

MCP es un protocolo distinto de nuestros endpoints REST. En lugar de llamar a rutas POST /v1/..., un cliente MCP habla JSON-RPC contra un único endpoint y descubre las herramientas disponibles para tu cuenta.

Endpoint

https://api.helmcode.com/mcp

Transporte: Streamable HTTP (remoto), stateless — no hay sesión que mantener viva.
Auth: Authorization: Bearer sk-your-key-here — la misma key sk-hke_ de tu panel.
Una petición sin autenticar o con una key inválida devuelve 401 Unauthorized.

Protocolo

El servidor habla JSON-RPC 2.0. Los métodos que usarás:

Método	Propósito
`initialize`	Handshake — negocia la versión del protocolo y las capacidades
`tools/list`	Lista las herramientas habilitadas para tu cuenta
`tools/call`	Invoca una herramienta con argumentos
`ping`	Comprobación de vida

Herramientas

El servidor es un registro de herramientas en crecimiento — se irán añadiendo más con el tiempo. La disponibilidad es por cuenta: una herramienta aparece en tools/list solo cuando está habilitada para tu organización.

`web_search`

Ejecuta una búsqueda web y devuelve resultados ordenados. Mismos argumentos que el endpoint REST POST /v1/search:

Argumento	Tipo	Por defecto	Notas
`query`	string	—	La consulta de búsqueda (obligatorio)
`count`	integer	`5`	Número de resultados, 1–20
`freshness`	string	—	`pd`, `pw`, `pm`, `py`, o un rango `YYYY-MM-DDtoYYYY-MM-DD`
`fetch_content`	boolean	`false`	Descarga y devuelve el contenido de cada página de resultado

Límites

Las llamadas MCP comparten el mismo presupuesto que la API REST — un único rate limit por key, cuota diaria y límite de concurrencia entre ambas superficies. Una búsqueda hecha por MCP cuenta exactamente igual que la misma búsqueda contra POST /v1/search. Consulta Rate limits.

Conectar en un cliente MCP

1. Remoto nativo (url + headers)

Los clientes que soportan servidores MCP remotos aceptan una URL y headers directamente:

{
  "mcpServers": {
    "helmcode": {
      "url": "https://api.helmcode.com/mcp",
      "headers": { "Authorization": "Bearer sk-your-key-here" }
    }
  }
}

2. Clientes solo-stdio con el puente `mcp-remote`

Si tu cliente solo habla stdio, haz de puente al servidor remoto con mcp-remote:

{
  "mcpServers": {
    "helmcode": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.helmcode.com/mcp",
        "--header",
        "Authorization:Bearer sk-your-key-here"
      ]
    }
  }
}

Consejo: mantén corto el nombre de la entrada del servidor (p. ej. helmcode). Muchos clientes prefijan cada herramienta con el nombre del servidor, así que helmcode muestra la herramienta como helmcode_web_search. Un nombre verboso como helmcode-web-search produciría un helmcode_web_search_web_search que parece duplicado.

Ejemplo JSON-RPC en crudo

Puedes llamar al servidor directamente con curl. Esto invoca web_search mediante tools/call:

curl https://api.helmcode.com/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "web_search",
      "arguments": { "query": "eu ai infrastructure", "count": 5 }
    }
  }'

Para descubrir qué está habilitado en tu cuenta, llama a tools/list de la misma forma:

curl https://api.helmcode.com/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'