MCP: usi OneType da Claude Code, Cursor e altri strumenti IA

OneType è un server MCP (Model Context Protocol, Streamable HTTP). Qualsiasi client MCP può chiamarlo con una chiave API: Claude Code, Cursor, Claude Desktop o i suoi agenti. I server sono due:

Server	URL	Per	Strumenti
Workspace	`https://api.onetype.ai/v1/mcp`	Il suo team e le sue automazioni: leggere agenti e conversazioni, cercare nella conoscenza, interrogare un agente e creare agenti	Strumenti di lettura: `list_agents`, `get_agent`, `list_conversations`, `get_conversation`, `list_messages`, `search_knowledge`, `ask_agent`. Strumenti di creazione: vedere Strumenti di creazione
Documentazione di un agente (fornito da OneType)	`https://api.onetype.ai/v1/mcp/agents/YOUR_AGENT_ID`	I suoi sviluppatori e clienti: le stesse risposte con citazioni della sua chat, direttamente nel loro editor	`search_docs`, `ask_agent`

Stato: entrambi i server sono Disponibili. Entrambi richiedono Premium: con Free le connessioni MCP vengono rifiutate con 422 PLAN_LIMIT.

1. Crei una chiave

Server workspace: in Developer › API keys, crei una chiave restricted (rk_live_…) e selezioni solo le autorizzazioni di cui ha bisogno:
- agents.read per list_agents e get_agent
- conversations.read per list_conversations, get_conversation e list_messages
- search.debug per search_knowledge
- conversations.write per ask_agent
- per uno strumento di creazione, l'autorizzazione della stessa azione nell'app (per esempio agents.update per update_agent, knowledge.write per add_website)
Documentazione di un agente: nella pagina MCP , apra la scheda dell'agente e crei la sua chiave. La chiave contiene mcp.agent ed è limitata a quel solo agente, quindi non può leggere nient'altro nel suo workspace. Può condividerla senza rischi con gli sviluppatori che usano la sua documentazione.

Le chiavi vengono mostrate una sola volta. La revoca ha effetto alla richiesta successiva.

2. Colleghi il suo client

Claude Code

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

Documentazione di 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 e altri client che accettano JSON:

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

Developer › MCP mostra entrambi gli snippet con il suo URL già inserito.

Poi chieda nel suo editor: “Usando onetype-docs, come verifico la firma di un webhook?” La risposta arriva con le sue fonti.

Cosa fa ogni strumento

Strumento	Server	Restituisce	Fatturazione
`list_agents`, `get_agent`	workspace	Agenti, così come li restituisce l'API REST	gratuito
`list_conversations`, `get_conversation`, `list_messages`	workspace	Conversazioni e relativi messaggi	gratuito
`search_knowledge`	workspace	I passaggi più pertinenti dalla conoscenza di un agente, con le fonti	gratuito
`search_docs`	un agente	I passaggi più pertinenti dalla conoscenza di quell'agente, con le fonti	gratuito
`ask_agent`	entrambi	Una risposta completa dell'agente, con citazioni	una risposta, come una risposta in chat

I passaggi, i messaggi e le risposte sono contrassegnati come contenuto non attendibile per il modello chiamante, quindi il testo nei suoi documenti non può dare istruzioni all'IA del client: su entrambi i server, ogni campo scritto dai suoi documenti, dai suoi visitatori o da un modello (di un passaggio header e text, di un messaggio text, di una fonte title, di un agente name e instructions) arriva come oggetto { "untrusted_text": "…" }, mai come semplice stringa. Legga la stringa da untrusted_text. Ogni chiamata viene registrata nel suo registro di controllo (mcp.tool.called). Il risultato di uno strumento non avvia mai nulla sul server.

Strumenti di creazione

Il server workspace crea ed esegue anche agenti. Ogni strumento funziona come la stessa azione nell'app: stesse autorizzazioni, stessi limiti del piano e stesso registro di controllo.

Gruppo	Strumenti
Account	`get_account`
Agenti	`list_models`, `create_agent`, `update_agent`, `publish_agent`, `take_agent_offline`, `resume_agent`, `delete_agent`
Conoscenza	`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 e sito	`set_allowed_domains`, `get_look`, `update_look`, `apply_look`, `set_bubble`, `get_install_snippet`, `test_agent` (fatturato come una risposta in chat)
Modelli e link	`list_templates`, `get_template`, `get_builder_prompt`, `get_checkout_link`, `get_connect_link`, `get_app_link`

Le chiamate distruttive attendono una persona. L'eliminazione di un agente, di una fonte o di una Q&A, la pubblicazione di un agente o il suo passaggio offline e, su un agente online, la pubblicazione del suo aspetto, la modifica dei suoi domini consentiti o la modifica di ciò che viene comunicato ai visitatori o di ciò che viene raccolto da loro, rispondono con needs_confirm e un link. Una persona che ha effettuato l'accesso a OneType lo approva nel browser; la stessa chiamata con confirm impostato sull'id indicato viene quindi eseguita una sola volta, entro 10 minuti. Anche il pagamento e il collegamento di altri strumenti avvengono nel browser, tramite i link restituiti dagli strumenti. Le modifiche sono limitate a 60 al minuto e create_agent a 10 all'ora.

Per gli sviluppatori di altri client MCP

POST accetta un solo messaggio JSON-RPC. initialize risponde con l'header Mcp-Session-Id ; lo invii nelle richieste successive.
Le versioni del protocollo supportate sono 2025-11-25 e 2025-06-18.
Metodi: ping, tools/list, tools/call. Le notifiche rispondono con 202. DELETE termina una sessione e GET risponde con 405. Le sessioni terminano dopo un giorno di inutilizzo.
tools/list offre uno strumento solo quando la chiave ne possiede l'autorizzazione.

Errori

Risposta	Significato	Soluzione
`401`	Chiave mancante o revocata	Verifichi `Authorization` nell'intestazione
`403 ORIGIN_NOT_ALLOWED`	Chiamato da una pagina del browser	Lo chiami da un server o da un client desktop. Le chiavi non devono mai stare in un browser
`403 AGENT_SCOPED_KEY`	La chiave di un agente usata sul server workspace	Usi l'URL dell'agente o una chiave del workspace
`403 AGENT_OUT_OF_SCOPE`, `422 PLAN_LIMIT`	La chiave non è per questo agente, oppure il workspace è su Free	Usi la chiave di quell'agente oppure passi a Premium
`400 SESSION_REQUIRED`, `PROTOCOL_VERSION_MISMATCH` · `404 SESSION_NOT_FOUND`	Gestione della sessione	Riesegua `initialize`
JSON-RPC `-32601` / `-32602`	Metodo sconosciuto, oppure strumento sconosciuto o argomenti non validi	Chiami `tools/list` per vedere cosa può usare questa chiave
Un risultato con `isError: true`	Lo strumento è stato rifiutato (per esempio per un'autorizzazione mancante)	Il suo codice e il suo messaggio ne spiegano il motivo

Le persone possono anche collegarsi con OAuth invece che con una chiave: claude.ai e Claude Desktop (un connettore personalizzato) e ChatGPT accedono tramite la schermata di consenso di OneType. La pagina MCP nell'app riporta i passaggi per ogni strumento.