Saltar para o conteúdo
Verificado

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:

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp

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

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

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 private sã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.

As chaves de VPS Full Stack trazem ferramentas extra

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:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

Seguinte