---
title: "Servidor MCP"
description: "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:

```text
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](/docs/pt/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.

<a id="add-it-to-a-client"></a>

## 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

```bash
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.

<a id="claude-desktop-and-claudeai"></a>

### 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](https://developers.openai.com/api/docs/guides/developer-mode) 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):

```json
{ "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`:

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

### Codex

```bash
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:

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

<a id="other-clients"></a>

### 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.

<a id="sign-in"></a>

## 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.

<a id="revoke-a-client"></a>

### 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.

<a id="what-a-connected-app-cannot-do"></a>

### 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.

<a id="personal-access-token"></a>

### 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:

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

<a id="tools"></a>

## Ferramentas

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

| Ferramenta | Parâmetros | O que faz |
| --- | --- | --- |
| `list_projects` | nenhum | Lista todos os projetos que você pode abrir, em todas as suas contas, com seu `project_id` e sua função. |
| `start_session` | `project_id`*, `prompt`*, `name`, `agent` | Inicia uma sessão em um projeto com um primeiro prompt. Retorna o `session_id`. |
| `send_message` | `session_id`*, `text`* | Enfileira uma mensagem para uma sessão e inicia a sessão se ela estiver parada. |
| `read_session` | `session_id`*, `limit`, `wait_seconds` | Retorna o status de uma sessão, informando se o turno está `idle`, `booting`, `running` ou `queued`, e suas mensagens mais recentes com a entrada e a saída de cada chamada de ferramenta. `limit` é 10 por padrão e 100 no máximo. `wait_seconds` (até 45) aguarda o término do turno. |
| `list_sessions` | `project_id`*, `limit`, `cursor` | Lista as sessões que você pode ver em um projeto: id, título, status, agente, proprietário, branch e datas. `limit` é 20 por padrão e 200 no máximo. |
| `run_command` | `session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel` | Executa um comando bash no sandbox de uma sessão e retorna stdout, stderr e o código de saída. Um comando longo retorna um `job_id` para continuar aguardando. |
| `read_file` | `path`*, `session_id`, `project_id`, `ref`, `offset`, `limit` | Lê um arquivo do sandbox de uma sessão ou do repositório git de um projeto em `ref`. Imagens são retornadas como imagens. |
| `write_file` | `session_id`*, `path`*, `content`*, `encoding` | Grava um arquivo no sandbox de uma sessão e cria seus diretórios-pai. `encoding` é `utf8` (padrão) ou `base64`. |
| `list_files` | `path`, `session_id`, `project_id`, `ref`, `offset` | Lista um diretório do sandbox de uma sessão ou todos os arquivos do repositório de um projeto em um caminho. |
| `read_skill` | `name`, `file`, `project_id` | Lista os guias da plataforma Beeuni ou retorna um guia (`name`) ou um de seus arquivos de referência (`file`). Com `project_id`, as skills próprias do projeto são listadas primeiro, e uma skill de projeto `name` retorna seu `SKILL.md` e os caminhos de seus arquivos de referência. |
| `list_connectors` | `project_id`*, `connector` | Lista os conectores de um projeto: slug, provedor, se cada um está `connected` (utilizável por você agora), quantidade de ações e contas. Com `connector`, lista todas as contas desse conector. |
| `search_connector_actions` | `project_id`*, `query`, `connector`, `limit` | Encontra ações de conectores por intenção. Retorna `tool` (`<connector>.<action>`), `risk` e uma descrição de uma linha. Nunca retorna schemas. |
| `describe_connector_action` | `project_id`*, `tool`* | Retorna o JSON Schema de entrada, o risco e a descrição de uma ação. |
| `call_connector` | `project_id`*, `tool`*, `args`, `account`, `reason` | Executa uma ação como você. Retorna os dados e o `account` que a executou, um resultado de `pending_approval` com o link de aprovação ou uma recusa com o motivo. |
| `upload_connector_attachment` | `project_id`*, `connector`*, `filename`*, `content_base64` ou `session_id` + `path` | Prepara um arquivo e retorna a referência `{"$beeuni_attachment": "<id>"}` para inserir em `args`. |
| `connect_connector` | `project_id`*, `connector`*, `owner`, `label` | Retorna o link que uma pessoa abre para conectar a conta do conector. |
| `search_connector_apps` | `project_id`*, `query`*, `limit`, `cursor` | Pesquisa o catálogo de aplicativos gerenciados dos quais um conector pode ser adicionado. |
| `add_connector` | `project_id`*, `app` ou `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url` | Adiciona um conector ao projeto agora (confirmado em `beeuni.yaml` em `main` e depois sincronizado). |
| `remove_connector` | `project_id`*, `connector`* | Remove um conector do projeto. |
| `beeuni` | `args`*, `project_id`, `session_id` | Executa a CLI real `beeuni` como você e retorna `exit_code`, `stdout` (ou `json` para saída `--json`) e `stderr`. Consulte [Executar qualquer comando da CLI](#run-any-cli-command). |
| `search_api` | `query`*, `limit` | Pesquisa as rotas da API Beeuni por palavra-chave. |
| `describe_api` | `method`*, `path`* | Retorna os parâmetros, o corpo da solicitação e o schema de resposta de uma rota. |
| `call_api` | `method`*, `path`*, `project_id`, `query`, `body` | Chama qualquer rota `/v1/` como você. `project_id` preenche `{projectId}` no caminho. |

`search_api`, `describe_api` e `call_api` abrangem tudo o que o aplicativo web e a
[CLI](/docs/pt/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.

<a id="run-any-cli-command"></a>

### Executar qualquer comando da CLI

A ferramenta `beeuni` executa a [CLI `beeuni`](/docs/pt/cli) 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.

```json
{ "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.

| Comando | Motivo | Use em vez disso |
| --- | --- | --- |
| qualquer sinalizador `--host` ou `--host=`, `hosts` | Direciona a CLI para outro servidor e enviaria seu token para lá. | Este servidor já atua como você. |
| `login`, `logout` | Login no navegador e tokens armazenados. | Você está conectado por meio da conexão MCP. |
| `init`, `ship`, `deploy` | Lê ou grava um diretório local. | `run_command` em um sandbox de sessão, onde o código-fonte está. |
| `tools` | Lê e edita um `beeuni.yaml` local, e o servidor não tem um checkout do projeto. | `run_command` em um sandbox de sessão: execute `beeuni tools ls` lá. |
| `apps deploy` | Faz o deploy de um diretório local, e o servidor não tem nenhum. | `run_command` em um sandbox de sessão: execute `beeuni apps deploy <path>` lá. |
| `env pull`, `env push` | Grava ou lê um arquivo local. | `secrets ls`, `secrets set KEY=value`. |
| `token`, `whoami --token-only` | Imprime o token de acesso bruto. | `whoami --json`. |
| `update`, `uninstall` | Altera a máquina que executa a CLI. | Nenhum. |
| `tui`, `t`, `connect`, `attach`, `sessions connect|shell|forward` | Exigem um terminal interativo. | `start_session`, `send_message`, `read_session`, `run_command`. |
| `chat` e `sessions chat` sem `--prompt` | Abrem um chat interativo. | `start_session`, `send_message` ou adicione `--prompt "<text>"`. |

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.

<a id="project-skills"></a>

### 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.

<a id="use-your-connectors"></a>

### Use seus conectores

As ferramentas de conector são a [`beeuni connectors`](/docs/pt/connect/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.

<a id="result-size-and-paging"></a>

### 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`.