MCP: use a OneType no Claude Code, no Cursor e em outras ferramentas de IA

A OneType é um servidor MCP (Model Context Protocol, Streamable HTTP). Qualquer cliente MCP pode chamá-lo com uma chave de API: Claude Code, Cursor, Claude Desktop ou os seus próprios agentes. Há dois servidores:

Servidor	URL	Para	Ferramentas
Workspace	`https://api.onetype.ai/v1/mcp`	Sua equipe e as suas próprias automações: ler agentes e conversas, buscar no conhecimento, perguntar a um agente e criar agentes	Ferramentas de leitura: `list_agents`, `get_agent`, `list_conversations`, `get_conversation`, `list_messages`, `search_knowledge`, `ask_agent`. Ferramentas de criação: veja Ferramentas de criação
Docs de um agente (fornecido pela OneType)	`https://api.onetype.ai/v1/mcp/agents/YOUR_AGENT_ID`	Seus desenvolvedores e clientes: as mesmas respostas com fontes do seu chat, dentro do editor deles	`search_docs`, `ask_agent`

Status: os dois servidores estão Disponíveis. Ambos exigem Premium: no Free, as conexões MCP são recusadas com 422 PLAN_LIMIT.

1. Crie uma chave

Servidor do workspace: em Developer › API keys, crie uma chave restrita (rk_live_…) e marque só as permissões de que precisa:
- agents.read para list_agents e get_agent
- conversations.read para list_conversations, get_conversation e list_messages
- search.debug para search_knowledge
- conversations.write para ask_agent
- para uma ferramenta de criação, a permissão da mesma ação no app (por exemplo agents.update para update_agent, knowledge.write para add_website)
Docs de um agente: na página MCP , abra o card do agente e crie a chave dele. A chave tem mcp.agent e é limitada a esse único agente, então não consegue ler mais nada no seu workspace. Você pode compartilhá-la com segurança com os desenvolvedores que usam as suas docs.

As chaves são mostradas uma única vez. Revogar uma chave vale a partir da próxima requisição.

2. Conecte seu cliente

Claude Code

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

Docs de um 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 outros clientes que aceitam JSON:

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

Developer › MCP mostra os dois trechos com a sua URL preenchida.

Depois pergunte no seu editor: “Using onetype-docs, how do I verify a webhook signature?” A resposta vem com as fontes.

O que cada ferramenta faz

Ferramenta	Servidor	Retorna	Cobrança
`list_agents`, `get_agent`	workspace	Agentes, como a REST API os retorna	grátis
`list_conversations`, `get_conversation`, `list_messages`	workspace	Conversas e suas mensagens	grátis
`search_knowledge`	workspace	Os trechos que melhor correspondem no conhecimento de um agente, com fontes	grátis
`search_docs`	um agente	Os trechos que melhor correspondem no conhecimento desse agente, com fontes	grátis
`ask_agent`	ambos	Uma resposta completa do agente, com citações	uma resposta, como uma resposta de chat

Trechos, mensagens e respostas são marcados como conteúdo não confiável para o modelo que chama, de modo que o texto dentro dos seus documentos não pode dar instruções à IA do cliente: nos dois servidores, todo campo que seus documentos, seus visitantes ou um modelo escreveram (o header e o text de um trecho, o text de uma mensagem, o title de uma fonte, o name e as instructions de um agente) chega como um objeto { "untrusted_text": "…" }, nunca como uma string solta. Leia a string em untrusted_text. Toda chamada é registrada no seu log de auditoria (mcp.tool.called). O resultado de uma ferramenta nunca inicia nada no servidor.

Ferramentas de criação

O servidor do workspace também cria e executa agentes. Cada ferramenta funciona como a mesma ação no app: com as mesmas permissões, limites de plano e o mesmo log de auditoria.

Grupo	Ferramentas
Conta	`get_account`
Agentes	`list_models`, `create_agent`, `update_agent`, `publish_agent`, `take_agent_offline`, `resume_agent`, `delete_agent`
Conhecimento	`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 site	`set_allowed_domains`, `get_look`, `update_look`, `apply_look`, `set_bubble`, `get_install_snippet`, `test_agent` (cobrada como uma resposta de chat)
Modelos e links	`list_templates`, `get_template`, `get_builder_prompt`, `get_checkout_link`, `get_connect_link`, `get_app_link`

Chamadas destrutivas esperam por uma pessoa. Excluir um agente, uma fonte ou um par de pergunta e resposta, publicar um agente ou tirá-lo do ar e, num agente no ar, publicar sua aparência, alterar seus domínios permitidos ou alterar o que se informa aos visitantes ou o que é coletado deles, respondem needs_confirm com um link. Uma pessoa conectada à OneType aprova no navegador; a mesma chamada com confirm definido com o id informado passa então uma vez, em até 10 minutos. Pagamento e conexão de outras ferramentas também acontecem no navegador, pelos links que as ferramentas retornam. As alterações são limitadas a 60 por minuto, e create_agent a 10 por hora.

Para desenvolvedores de outros clientes MCP

POST recebe uma mensagem JSON-RPC. initialize responde com o header Mcp-Session-Id ; envie-o nas requisições seguintes.
As versões de protocolo suportadas são 2025-11-25 e 2025-06-18.
Métodos: ping, tools/list, tools/call. Notificações respondem 202. DELETE encerra uma sessão, e GET responde 405. As sessões terminam após um dia sem uso.
tools/list só oferece uma ferramenta quando a chave tem a permissão dela.

Erros

Resposta	Significado	Correção
`401`	Chave ausente ou revogada	Confira o `Authorization` header
`403 ORIGIN_NOT_ALLOWED`	Chamada feita a partir de uma página do navegador	Chame a partir de um servidor ou de um cliente desktop. Chaves nunca pertencem a um navegador
`403 AGENT_SCOPED_KEY`	A chave de um agente usada no servidor do workspace	Use a URL do agente ou uma chave do workspace
`403 AGENT_OUT_OF_SCOPE`, `422 PLAN_LIMIT`	A chave não é deste agente, ou o workspace está no Free	Use a chave desse agente ou faça upgrade para o Premium
`400 SESSION_REQUIRED`, `PROTOCOL_VERSION_MISMATCH` · `404 SESSION_NOT_FOUND`	Tratamento de sessão	Execute de novo `initialize`
JSON-RPC `-32601` / `-32602`	Método desconhecido, ou ferramenta desconhecida ou argumentos inválidos	Chame `tools/list` para ver o que esta chave pode usar
Um resultado com `isError: true`	A ferramenta foi recusada (p. ex. por falta de permissão)	O código e a mensagem dela explicam o motivo

As pessoas também podem se conectar com OAuth em vez de uma chave: claude.ai e Claude Desktop (um conector personalizado) e o ChatGPT entram pela tela de consentimento da OneType. A página MCP no app tem os passos para cada ferramenta.