MCP
A mesma chave de API, exposta a um agente de IA como uma ferramenta tipada por cada método permitido.
A Xuda executa um servidor Model Context Protocol em /mcp, junto a /cpi. Ligue-lhe um agente compatível com MCP,
iniciando sessão ou com uma chave de API, e todos os métodos que essa chave pode chamar aparecem como uma
ferramenta tipada, sem uma integração separada para os agentes de IA escreverem.
Ligar
Há duas formas de entrar e ambas terminam no mesmo sítio: os direitos de uma chave de API.
Iniciar sessão (conectores do Claude e outros clientes OAuth)
Adicione https://xuda.ai/mcp como conector personalizado no Claude (Definições, Conectores, Adicionar
conector personalizado), deixe vazios o ID de cliente e o segredo OAuth e prima Ligar. O Claude abre
a Xuda: inicie sessão se ainda não o fez, e uma janela no painel pergunta qual das suas chaves de API a
ligação utiliza; escolha uma e prima Ligar. O Claude na web, no Desktop, no telemóvel e no Cowork
partilham essa ligação, e qualquer outra conta Claude a adiciona da mesma forma. O separador Programadores, MCP
do painel mostra o endereço a colar, estes passos e tudo o que se segue.
O Claude Code inicia sessão da mesma forma quando adiciona o servidor sem cabeçalho, depois execute /mcp e
escolha Authenticate:
A ligação nunca tem direitos próprios. Cada chamada de ferramenta é executada como a chave que escolheu, por isso o modo de acesso, a lista de permissões e a revogação da chave são também os da ligação: revogue a chave em Programadores, Chaves de API e a ligação pára, e o início de sessão seguinte pede outra chave. A página lista apenas as suas próprias chaves ativas; se não tiver nenhuma, crie primeiro uma.
Para programadores de clientes, o servidor segue a especificação de autorização do MCP:
Uma chamada a /mcp sem um token utilizável responde 401 com WWW-Authenticate: Bearer resource_metadata="...", que é como um cliente descobre o resto. Os tokens de acesso duram uma hora; os tokens de
atualização duram 90 dias e são substituídos a cada utilização. Um URI de redirecionamento loopback (http://localhost ou
http://127.0.0.1) corresponde em qualquer porta.
Uma chave de API num cabeçalho
A chave vai num cabeçalho Authorization: Bearer, a mesma chave que utilizaria como api_key em
/cpi. Não existe uma credencial MCP separada. Um pedido sem cabeçalho Authorization, ou com uma chave
que não corresponda a um documento xuda_api_keys ativo, é recusado com 401 antes de qualquer ferramenta
ser registada.
Sessões
O transporte é HTTP em streaming: o primeiro pedido é uma chamada MCP initialize, que abre uma
sessão e devolve um cabeçalho mcp-session-id; todos os pedidos seguintes nessa ligação levam
o mesmo cabeçalho e a mesma credencial. Uma sessão fecha após 10 minutos sem pedidos. Um
pedido numa sessão que já fechou responde 404, e um cliente MCP inicia então uma nova sessão por
si só.
O que se torna uma ferramenta
As ferramentas são registadas no início da sessão a partir do mesmo modo de acesso que a chave já tem:
- Acesso total: todos os métodos do catálogo que não sejam
privatesão registados como ferramenta, resolvidos no momento da ligação, pelo que um método adicionado depois de a chave ter sido criada fica disponível sem alterar a própria chave. - Acesso personalizado: apenas os métodos da lista de permissões da chave são registados.
Uma sessão em curso acompanha a sua chave: verifica a chave a cada minuto, e os módulos e
plugins por trás dela a cada cinco, e quando o conjunto de ferramentas mudou envia
notifications/tools/list_changed. Um cliente que escute (o Claude escuta) lê a nova lista sem
voltar a ligar-se, pelo que um método que permita na chave chega a um agente que já está ligado.
Cada ferramenta mantém a forma do próprio método: o nome da ferramenta é o nome do método (get_account_projects,
dbs_read, ...), o seu título é o nome do método em Title Case, a sua descrição é a description do próprio
método e o seu esquema de entrada é construído campo a campo a partir dos fields do método; os campos obrigatórios
continuam obrigatórios e tudo o resto é opcional. Um campo sem tipo reconhecido continua a tornar-se um
argumento de ferramenta permissivo em vez de quebrar a sessão inteira, pelo que um método mal especificado
nunca derruba o resto do catálogo.
Uma chave limitada a um VPS Full Stack também expõe as ferramentas dos plugins instalados nessa máquina, a par dos métodos do ecossistema acima, para que um agente alcance a plataforma e tudo o que o programador criou na máquina numa única sessão. Consulte VPS Full Stack.
Chamar uma ferramenta
Um agente chama uma ferramenta com os mesmos argumentos que os campos do método descrevem. A Xuda responde
chamando o método internamente, da mesma forma que /cpi/<method> o faria, e devolve à ferramenta o envelope
{code, data} do método como texto. Uma chamada falhada continua a devolver normalmente na camada MCP, o código
-1 e inferiores aparece no resultado da ferramenta exatamente como numa chamada REST simples, pelo que um agente o lê
da mesma forma que o seu próprio tratamento de erros o leria. Consulte Erros.
Um pedido que falha antes de qualquer ferramenta correr, uma credencial em falta ou recusada (401), uma sessão
que fechou (404, código -32001), uma mensagem MCP mal formada, volta como um erro JSON-RPC
em vez de um resultado de ferramenta: