Servidor MCP

Conecte Claude, ChatGPT, Cursor, VS Code, Codex ou qualquer cliente MCP ao Beeuni via OAuth ou um token de acesso pessoal. Um único URL dá acesso a todos os projetos que você pode abrir. Nada para instalar.

Experimental. Suas ferramentas podem mudar sem aviso de descontinuação.

O Beeuni tem um servidor MCP hospedado:

https://api.beeuni.ai/v1/mcp

Adicione esse URL a um cliente MCP uma vez. Na primeira chamada, você precisará entrar no Beeuni pelo navegador. Depois disso, o cliente agirá como você, com suas permissões, em todas as contas e projetos que você pode abrir — o mesmo alcance da CLI. O URL não especifica um projeto: as ferramentas recebem um project_id ou um session_id, e list_projects os lista. Não é preciso instalar nada.

Adicionar a um cliente

Todos os clientes abaixo conectam você por OAuth no primeiro uso, a menos que as instruções mencionem um token. Não substitua nada: o URL é o mesmo para todos os projetos.

Claude Code

claude mcp add --transport http beeuni https://api.beeuni.ai/v1/mcp

Execute /mcp no Claude Code e entre na sua conta. Para usar um token de acesso pessoal, adicione --header "Authorization: Bearer $BEEUNI_TOKEN" ao comando.

Claude Desktop e claude.ai

Settings → Connectors → Add custom connector. Cole o URL e entre na sua conta.

ChatGPT

Conectores MCP personalizados exigem o modo de desenvolvedor. De acordo com o guia do modo de desenvolvedor da OpenAI, ative o Developer mode em Settings → Security and login e crie um app no modo de desenvolvedor pela página de plugins do ChatGPT (botão de adição). Insira o URL e escolha a autenticação OAuth. A OpenAI informa os planos e os nomes dos menus, que podem mudar: consulte esse guia se algum rótulo for diferente.

Cursor

Use o botão Add to Cursor em Connect MCP ou adicione o servidor a ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto):

{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp" } } }

VS Code

Adicione o servidor a .vscode/mcp.json. O VS Code usa servers, não mcpServers, e precisa de type:

{ "servers": { "beeuni": { "type": "http", "url": "https://api.beeuni.ai/v1/mcp" } } }

Codex

codex mcp add beeuni --url https://api.beeuni.ai/v1/mcp
codex mcp login beeuni

Ou edite ~/.codex/config.toml. Para usar um token de acesso pessoal, indique a variável de ambiente que o contém:

[mcp_servers.beeuni]
url = "https://api.beeuni.ai/v1/mcp"
bearer_token_env_var = "BEEUNI_TOKEN"

Outros clientes

Adicione um servidor MCP remoto (Streamable HTTP) usando o URL. Um cliente que não consegue executar OAuth envia um token de acesso pessoal em um cabeçalho (abaixo).

Abra o menu do espaço de trabalho (o nome do projeto, no canto superior esquerdo) e selecione Connect MCP para copiar o URL e as instruções para Claude, Claude Code, Cursor e Codex.

Fazer login

O servidor usa o fluxo OAuth 2.1 definido pela especificação MCP. O cliente o executa sem precisar de configuração:

1. Uma chamada sem token retorna 401 com WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni".
2. O cliente lê o documento RFC 9728 em /.well-known/oauth-protected-resource/v1/mcp. Ele identifica o Beeuni como servidor de autorização.
3. O cliente se registra em POST /v1/oauth/register (RFC 7591). Ele recebe um cliente público que se autentica somente com PKCE.
4. Você aprova o cliente na tela de consentimento do Beeuni. Um cliente autorregistrado é identificado como Unverified app, junto com o host para o qual ele redireciona você. Aprove-o somente se você mesmo estiver conectando o cliente.
5. O cliente troca o código por um token de acesso beeuni_oat_ (válido por 1 hora) e um token de atualização (válido por 30 dias, com rotação a cada uso). Quando o token de acesso expira, o cliente o atualiza sem pedir que você faça login novamente.

Revogar um cliente

Settings → Personal access keys → Connected apps lista todos os apps que você aprovou em todas as suas contas: o nome, onde fazem login e quando estiveram ativos pela última vez. Um cliente MCP autorregistrado é identificado como Unverified app. Revoke access remove sua aprovação e revoga os tokens: a próxima solicitação do cliente falha, e ele precisa pedir sua aprovação novamente. No terminal: beeuni tokens apps ls e beeuni tokens apps rm <client-id>. Ambos funcionam somente em uma sessão do navegador ou com um token de acesso pessoal, nunca com o token do próprio app.

O que um app conectado não pode fazer

O escopo beeuni age em seu nome: um app conectado lê e altera o que você pode ler e alterar. Ele não pode criar uma credencial que dure mais que seu próprio token revogável. Estas rotas retornam 403 para um token beeuni_oat_:

• tokens de acesso pessoal (POST /v1/accounts/tokens) e tokens de CLI do projeto;
• chaves de gateway;
• tokens SCIM;
• clientes OAuth e a rotação dos segredos deles;
• contas de serviço;
• a lista de apps conectados e sua revogação (/v1/oauth/grants).

Revogue um cliente e o acesso dele será encerrado. Um token de acesso pessoal é diferente: ele não expira, a menos que você passe --expires, e revogar um app não o revoga.

Token de acesso pessoal

Um cliente sem OAuth ou um script envia um token beeuni_pat_ — o token usado pela CLI. Crie um com beeuni tokens new <name> ou em Settings → Personal access keys e, em seguida, envie-o como cabeçalho:

{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp", "headers": { "Authorization": "Bearer beeuni_pat_…" } } } }

Ferramentas

tools/list retorna 23 ferramentas. Os parâmetros marcados com * são obrigatórios.

search_api, describe_api e call_api abrangem tudo o que o aplicativo web e a CLI fazem, pois ambos são clientes da mesma API. call_api recusa /v1/oauth/* e qualquer caminho que alcance um endpoint MCP. Preencha todos os outros {placeholder} no caminho por conta própria. Cada chamada usa a mesma autorização e auditoria de uma solicitação do aplicativo web. A auditoria registra cada chamada com credential_kind: "oauth_app" e o nome do aplicativo conectado, pois a API registra a credencial que autenticou, não um rótulo enviado pelo cliente.

Executar qualquer comando da CLI

A ferramenta beeuni executa a CLI beeuni real como você. Todo comando da CLI funciona por meio dela, então o servidor MCP tem o mesmo alcance de um terminal: secrets, triggers, cr, review, lembretes, agentes, modelos, gateway, provedores, canais, sandboxes, aplicativos, marketplace, arquivos, acesso, funções, permissões, auditoria, concessões, membros, grupos, tokens, cobrança, projetos, sessões e system-skills. Uma ferramenta substitui cerca de 200 ferramentas de subcomandos, o que ultrapassaria o limite de ferramentas de clientes como o Cursor.

args são os argumentos após beeuni, um elemento do array por argumento. Nunca é uma linha de shell.

{ "name": "beeuni", "arguments": { "args": ["--help"] } }
{ "name": "beeuni", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["system-skills"] } }

• Descubra com ["--help"] e ["<group>", "--help"]. Adicione --json à saída que você analisa.
• project_id define o projeto de um comando com escopo de projeto. session_id define a sessão de um comando que atua sobre uma.
• O resultado é JSON: exit_code, stdout, stderr. Com --json, a saída do comando chega como um valor JSON em json em vez de stdout. A saída que não couber é cortada e marcada como truncated; JSON cortado não é JSON válido, então reduza o comando. Um exit_code diferente de zero é um erro MCP. Cada fluxo é cortado em 24.000 (stdout) e 8.000 (stderr) caracteres, e o resultado informa isso em truncated.
• Um comando que seja executado por mais de aproximadamente 45 segundos é encerrado. O resultado contém timed_out.
• O servidor executa no máximo 4 comandos da CLI simultaneamente. Uma quinta chamada retorna Busy: tente novamente.
• Sessões, arquivos do sandbox e conectores têm ferramentas próprias (start_session, run_command, read_file, call_connector). Dê preferência a elas.

A CLI é executada no servidor com seu próprio token, nesta API. Ela não recebe credenciais do servidor: o ambiente contém apenas seu token, a URL da API, os IDs do projeto e da sessão, além de um diretório home temporário e um diretório de trabalho vazios. O servidor remove ambos após o comando. A autorização e a auditoria são da API: um token externo recebe o mesmo 403 que receberia em um terminal.

Estes comandos são recusados antes de qualquer execução. O erro informa o motivo e a alternativa.

A auditoria registra um comando da CLI com a mesma credencial de todas as outras chamadas na conexão (credential_kind: "oauth_app"). Ela não consegue distinguir a ferramenta beeuni da call_api: ambas acessam a API com seu token.

Skills do projeto

read_skill com um project_id lista as próprias skills do projeto (os arquivos skills/<slug>/SKILL.md do repositório ou o .beeuni/opencode/skills/ legado) antes dos guias da plataforma. Passe a skill name para ler seu SKILL.md e os caminhos dos arquivos de referência, e file para ler uma referência. Você vê as skills permitidas pela sua função e pelas suas concessões.

Use seus conectores

As ferramentas de conector são a beeuni connectors CLI como ferramentas MCP. Elas chamam as mesmas rotas da API que a CLI e o SDK, portanto uma política de conector, uma aprovação e a auditoria funcionam da mesma forma em todas as interfaces.

1. list_connectors mostra o que está conectado. Um conector com connected: false não pode executar ações: chame connect_connector, abra o link retornado e liste novamente.
2. search_connector_actions encontra uma ação por intenção, por exemplo, send an email. describe_connector_action retorna seus argumentos.
3. call_connector a executa. O resultado informa o account que executou a chamada. Um conector com várias contas e sem uma conta padrão precisa de account.
4. Passe reason em uma gravação cujos argumentos sejam apenas IDs (send_draft, exclusão por ID). O aprovador os vê ao lado dos argumentos reais.

Uma política pode reter uma chamada para aprovação. call_connector então retorna status: "pending_approval" com um approval_url. Uma pessoa o abre e aprova. Faça a chamada novamente com a mesma ferramenta, os mesmos argumentos e a mesma conta dentro de 15 minutos: a chamada aprovada é executada uma vez. Uma recusa de policy_block é definitiva.

Um resultado com mais de aproximadamente 40.000 caracteres retorna como uma prévia marcada (data_truncated). Restrinja os argumentos e chame novamente. Para anexar um arquivo, prepare-o com upload_connector_attachment e coloque a referência retornada em args. Os conectores com o provedor composio não aceitam referências de anexos.

Tamanho dos resultados e paginação

• O resultado de uma ferramenta é cortado em 60.000 caracteres e termina com …[truncated at 60000 chars].
• read_file retorna um arquivo de texto longo em páginas de até aproximadamente 50.000 caracteres. Um resultado cortado termina com o offset que dá continuidade a ele. offset ignora linhas e limit limita as linhas retornadas. Um arquivo binário não é retornado como texto: leia-o com run_command.
• list_files corta uma lista longa da mesma forma. Passe o offset que ele informa.
• list_sessions retorna next_cursor quando há mais sessões. Passe-o de volta como cursor.
• read_session retorna as mensagens limit mais recentes. Ele corta cada entrada e saída de ferramenta e remove as mensagens mais antigas quando o resultado não cabe (omitted_older). last_turn_error informa um turno com falha.
• Uma solicitação MCP é respondida em até 55 segundos. read_session com wait_seconds e um sandbox que ainda está iniciando são interrompidos antes disso: chame novamente.

Sandboxes

run_command, read_file, write_file e list_files com um session_id acessam o sandbox ativo da sessão, da mesma forma que o terminal web e o painel de arquivos. Os caminhos relativos são resolvidos em /workspace, o checkout git da sessão. Um sandbox parado é iniciado na primeira chamada. A CLI beeuni no sandbox está conectada como a sessão. Com um project_id e sem session_id, read_file e list_files leem o repositório git do projeto e não iniciam nenhum sandbox.

Um comando pode ser executado por vários minutos. Uma chamada de ferramenta aguarda cerca de 50 segundos. Quando o comando ainda está em execução nesse momento, run_command retorna status: running, um job_id e a saída até o momento. Chame run_command com esse job_id para continuar aguardando ou com cancel: true para interrompê-lo. timeout_seconds (padrão 600, máximo 86400) interrompe um comando executado por tempo excessivo, com código de saída 124. A saída é mantida em ~/.cache/beeuni-mcp/jobs/<job_id>/ no sandbox; o resultado da ferramenta mostra os últimos 24.000 bytes de cada fluxo. Um sandbox que para encerra também os comandos em execução.

O servidor é sem estado: responde a POST com JSON e a GET e DELETE com 405.