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 Integraciones → Claves de API.
- Presiona Crear clave de API y ponle el nombre de la app o la máquina que la usará, por ejemplo “Cursor en mi laptop”.
- Copia la clave de inmediato. TypeHop solo guarda un hash, así que la clave completa se muestra una sola vez. ¿La perdiste? Crea una nueva y revoca la anterior.
Las claves empiezan con thp_mcp_. La lista en 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 de inmediato.
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. - Encabezado
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 las personas 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 Conectar una app, con tu nueva clave ya incluida. 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 sobre Streamable HTTP funciona con la URL del endpoint y el encabezado de arriba. 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, con una respuesta JSON. No guarda estado, así que no hay encabezados de sesión ni eventos enviados por el servidor. 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 en un resultado empieza con una línea de encabezado: [created at · app · id <id>], seguida del texto limpio. Pasa ese id a get_dictation para obtener la transcripción sin procesar. También puedes enviar un arreglo de hasta 20 mensajes en una sola solicitud; las notificaciones (mensajes sin id) reciben 202 sin cuerpo. Se admite ping.
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 sobre 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, valor predeterminado 20)
recent_dictations · Dictados recientes
Los últimos dictados del usuario, opcionalmente solo de los últimos días.
limit(integer 1–50, valor predeterminado 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 sin procesar.
id(string, obligatorio): El id que aparece en los resultados de búsqueda o recientes.
list_dictionary · Palabras personalizadas
Las palabras y ortografías personalizadas del usuario (nombres, jerga).
Sin argumentos.
Cuando una herramienta no puede responder (una consulta vacía, un id desconocido, una falla temporal de lectura), la respuesta sigue siendo un resultado 200, con isError: true y una oración 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 el encabezado Authorization, o la clave no es válida o fue revocada.400 · -32700El cuerpo no es 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 nombró 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 hacia 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 máquina, para poder revocar una sin afectar a las demás.
- Guarda las claves en tu computadora o en tu backend. Nunca las pongas en código del navegador, en el paquete de una app móvil ni en un repositorio público.
- Si una clave se filtra: revócala en Integraciones → Claves de API. Dejará de funcionar en la siguiente solicitud.
Preguntas: support@typehop.com. ¿Buscas una descripción general? Consulta la API de TypeHop.