Desarrolladores · Claves de API
Referencia de las claves de API de TypeHop
Una clave de API permite que una app de IA o tu propio código lea los dictados sincronizados con tu cuenta de TypeHop, desde cualquier dispositivo. Las claves son de solo lectura: pueden buscar y leer dictados y tus palabras personalizadas, pero nunca modificar ni eliminar nada. El acceso se hace a través de un único endpoint MCP remoto, así que apps como Claude Code, Cursor y Codex funcionan con una sola línea de configuración.
Crear una clave
- Abre la app de TypeHop para Mac y ve a Integrations → API keys.
- Pulsa Create API key y ponle el nombre de la app o del equipo que la va a usar, por ejemplo “Cursor en mi portátil”.
- Copia la clave de inmediato. TypeHop solo guarda un hash, así que la clave completa se muestra una sola vez. ¿La has perdido? Crea una nueva y revoca la anterior.
Las claves empiezan por thp_mcp_. La lista de la app muestra los primeros caracteres de cada clave, cuándo se creó y cuándo se usó por última vez. Al revocar una clave, todas las apps que la usan dejan de tener acceso al instante.
Autenticación
Envía la clave como token Bearer en cada solicitud. No hay flujo de OAuth ni sesión que abrir.
- Endpoint
https://api.typehop.com/v1/mcp- Método
- Solo
POST.GETyDELETEdevuelven 405. - Cabecera
Authorization: Bearer thp_mcp_YOUR_KEY- Cuerpo
- JSON-RPC 2.0,
Content-Type: application/json
Una clave ausente o revocada
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="typehop-mcp"
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "This token is invalid or was revoked." } }Conectar una app de IA
La mayoría de la gente nunca llama al endpoint a mano. La app para Mac muestra la configuración exacta para Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed y Claude Desktop en Connect an app, con tu nueva clave ya rellenada. Los mismos fragmentos están en la página de MCP. Por ejemplo, Claude Code:
claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"
Cualquier otro cliente que admita servidores MCP remotos mediante Streamable HTTP funciona con la URL del endpoint y la cabecera anteriores. Los conectores personalizados de Claude.ai y ChatGPT requieren OAuth, que TypeHop todavía no admite.
Llamarlo desde código
El endpoint habla el Model Context Protocol: mensajes JSON-RPC 2.0 en un POST y una respuesta JSON de vuelta. No tiene estado, así que no hay cabeceras de sesión ni server-sent events. Versiones del protocolo admitidas: 2025-06-18, 2025-03-26, 2024-11-05.
1. Inicializar (opcional, pero los clientes MCP lo hacen)
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'2. Listar las herramientas
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. Llamar a una herramienta
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_dictations","arguments":{"query":"launch plan","limit":5}}}'Respuesta · 200
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "[2026-11-03T09:14:22.000Z · Slack · id 3f6c1a2e-8b1d-4c55-9a0e-6b2f7d1e4c90]\nThe launch plan moves to next Tuesday..."
}
],
"isError": false
}
}Cada dictado de un resultado empieza con una línea de cabecera: [created at · app · id <id>], seguida del texto limpio. Pasa ese id a get_dictation para obtener la transcripción en bruto. También puedes enviar un array de hasta 20 mensajes en una sola solicitud; las notificaciones (mensajes sin id) reciben 202 sin cuerpo. ping es compatible.
Herramientas
Todas las herramientas son de solo lectura y devuelven texto plano en result.content[0].text.
search_dictations · Buscar dictados
Búsqueda de texto completo en todo lo que el usuario ha dictado. Devuelve primero las coincidencias más recientes.
query(string, obligatorio): Palabras o frase que buscar.limit(integer 1–50, por defecto 20)
recent_dictations · Dictados recientes
Los últimos dictados del usuario, opcionalmente solo de los últimos días.
limit(integer 1–50, por defecto 20)days(integer 1–365): Solo dictados de los últimos N días.
get_dictation · Obtener un dictado
Un dictado por id: el texto limpio y la transcripción en bruto.
id(string, obligatorio): El id que aparece en los resultados de búsqueda o recientes.
list_dictionary · Palabras personalizadas
Las palabras y grafías personalizadas del usuario (nombres, jerga).
Sin argumentos.
Cuando una herramienta no puede responder (una consulta vacía, un id desconocido, un fallo de lectura temporal), la respuesta sigue siendo un resultado 200, con isError: true y una frase que el modelo puede leer.
Errores
Los errores de protocolo se devuelven como un objeto error de JSON-RPC: { "code": <number>, "message": "<text>" }.
401 · -32001Falta la cabecera Authorization, o la clave no es válida o está revocada.400 · -32700El cuerpo no es un JSON válido.413 · -32600El cuerpo supera los 256 KB.200 · -32600El mensaje no es JSON-RPC 2.0 (falta "jsonrpc": "2.0" o "method").200 · -32601Método desconocido.200 · -32602tools/call nombraba una herramienta que no existe.500 · -32603Error del servidor. Reintenta con espera progresiva.
Límites y seguridad
- Claves activas
- Hasta 10 por cuenta. Revoca una para crear otra.
- Tamaño de la solicitud
- 256 KB por solicitud, hasta 20 mensajes por lote.
- Resultados
- Hasta 50 dictados por llamada;
recent_dictationsmira atrás un máximo de 365 días. - Alcance
- Los dictados sincronizados con tu cuenta, además de tus palabras personalizadas. No se escribe nada.
- Usa una clave por app o por equipo, para poder revocar una sin afectar a las demás.
- Guarda las claves en tu ordenador o en tu backend. Nunca las pongas en código de navegador, en el paquete de una app móvil ni en un repositorio público.
- Si se filtra una clave: revócala en Integrations → API keys. Dejará de funcionar en la siguiente solicitud.
Preguntas: support@typehop.com. ¿Buscas una visión general? Consulta la API de TypeHop.