---
title: "MCP сервер"
description: "Повежите Claude, ChatGPT, Cursor, VS Code, Codex или било који MCP клијент са Beeuni-јем преко OAuth-а или личног приступног токена. Један URL омогућава приступ сваком пројекту који можете да отворите. Ништа не треба да инсталирате."
---

> **Експериментално.** Алати се могу изменити без претходне најаве.

Beeuni има један хостовани MCP сервер:

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

Додајте тај URL у MCP клијент једном. При првом позиву затражиће од вас да се пријавите на Beeuni у прегледачу. Након тога, клијент поступа у ваше име, са вашим дозволама, у свим налозима и пројектима које можете да отворите — баш као и [CLI](/docs/sr/cli). URL не наводи ниједан пројекат: алати примају `project_id` или `session_id`, а `list_projects` их излистава. Ништа не треба инсталирати.

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

## Додавање у клијент

Сваки клијент у наставку при првој употреби пријављује вас преко OAuth-а, осим ако у корацима није наведен токен. Не мењајте ништа: URL је исти за сваки пројекат.

### Claude Code

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

Покрените `/mcp` у Claude Code-у и пријавите се. Ако уместо тога желите да користите лични приступни токен, додајте `--header "Authorization: Bearer $BEEUNI_TOKEN"` у команду.

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

### Claude Desktop и claude.ai

**Settings → Connectors → Add custom connector**. Налепите URL и пријавите се.

### ChatGPT

За прилагођене MCP конекторе потребан је режим за програмере. Према OpenAI-јевом [водичу за режим за програмере](https://developers.openai.com/api/docs/guides/developer-mode), укључите **Developer mode** у **Settings → Security and login**, а затим на страници ChatGPT plugins направите апликацију у режиму за програмере (дугме плус). Унесите URL и изаберите начин потврде идентитета **OAuth**. OpenAI наводи подржане планове и називе ставки у менију, који се мењају: пратите тај водич ако се нека ознака разликује.

### Cursor

Употребите дугме **Add to Cursor** у одељку **Connect MCP** или додајте сервер у `~/.cursor/mcp.json` (за све пројекте) или `.cursor/mcp.json` (за један пројекат):

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

### VS Code

Додајте сервер у `.vscode/mcp.json`. VS Code користи `servers`, а не `mcpServers`, и потребан му је `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
```

Или уредите `~/.codex/config.toml`. За лични приступни токен наведите име променљиве окружења у којој се он чува:

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

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

### Други клијенти

Додајте удаљени MCP сервер (Streamable HTTP) помоћу URL-а. Клијент који не подржава OAuth шаље лични приступни токен у заглављу (у наставку).

Отворите мени радног простора (назив пројекта, горе лево) и изаберите **Connect MCP** да бисте копирали URL и кораке за Claude, Claude Code, Cursor и Codex.

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

## Пријављивање

Сервер користи OAuth 2.1 ток који дефинише MCP спецификација. Клијент га обавља без подешавања:

1. Позив без токена добија одговор `401` са `WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"`.
2. Клијент чита RFC 9728 документ на адреси `/.well-known/oauth-protected-resource/v1/mcp`. У њему је Beeuni наведен као сервер за ауторизацију.
3. Клијент се региструје на адреси `POST /v1/oauth/register` (RFC 7591). Добија јавног клијента који се потврђује искључиво помоћу PKCE-а.
4. Одобравате клијента на екрану за сагласност Beeuni-ја. Самостално регистрован клијент означен је као **Unverified app**, уз назив хоста на који вас враћа. Одобрите га само ако га сами повезујете.
5. Клијент размењује код за приступни токен `beeuni_oat_` (важи 1 сат) и токен за освежавање (важи 30 дана, ротира се при употреби). Када приступни токен истекне, клијент га освежава без поновног тражења ваше сагласности.

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

### Опозивање приступа клијенту

У одељку **Settings → Personal access keys → Connected apps** приказане су све апликације које сте одобрили, на свим својим налозима: њихов назив, место пријављивања и време последње активности. Самостално регистровани MCP клијент означен је као **Unverified app**. Опција **Revoke access** брише ваше одобрење и опозива његове токене: следећи захтев неће успети и клијент ће морати поново да затражи одобрење. Из терминала покрените: `beeuni tokens apps ls` и `beeuni tokens apps rm <client-id>`. Обе команде раде само из сесије прегледача или помоћу личног приступног токена, никада помоћу токена саме апликације.

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

### Шта повезана апликација не може да уради

Опсег `beeuni` омогућава поступање у ваше име: повезана апликација може да чита и мења оно што и ви можете да читате и мењате. Не може да направи акредитив који важи дуже од сопственог токена који се може опозвати. Ове путање враћају `403` за токен `beeuni_oat_`:

- лични приступни токени (`POST /v1/accounts/tokens`) и CLI токени пројеката;
- кључеви мрежног пролаза;
- SCIM токени;
- OAuth клијенти и ротација њихових тајни;
- сервисни налози;
- списак повезаних апликација и опозив њиховог приступа (`/v1/oauth/grants`).

Опозовите приступ клијенту и он ће изгубити приступ. Лични приступни токен је другачији: он не истиче осим ако не проследите `--expires`, а опозив приступа апликацији не опозива и њега.

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

### Лични приступни токен

Клијент без OAuth-а или скрипта уместо тога шаље токен `beeuni_pat_` — исти токен који користи CLI. Направите га помоћу `beeuni tokens new <name>` или у одељку **Settings → Personal access keys**, а затим га пошаљите као заглавље:

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

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

## Алати

`tools/list` враћа 23 алата. Параметри означени звездицом * су обавезни.

| Алат | Параметри | Шта ради |
| --- | --- | --- |
| `list_projects` | нема | Наводи све пројекте које можете да отворите, на свим својим налозима, са њиховим `project_id` и вашом улогом. |
| `start_session` | `project_id`*, `prompt`*, `name`, `agent` | Покреће сесију у пројекту са почетним упитом. Враћа `session_id`. |
| `send_message` | `session_id`*, `text`* | Ставља поруку у ред за сесију и покреће сесију ако је заустављена. |
| `read_session` | `session_id`*, `limit`, `wait_seconds` | Враћа статус сесије, да ли је њен потез `idle`, `booting`, `running` или `queued`, као и најновије поруке и улазне и излазне податке сваког позива алата. `limit` је подразумевано 10, а највише 100. `wait_seconds` (до 45) чека да се потез заврши. |
| `list_sessions` | `project_id`*, `limit`, `cursor` | Наводи сесије које можете да видите у пројекту: ИД, наслов, статус, агент, власник, грана, датуми. `limit` је подразумевано 20, а највише 200. |
| `run_command` | `session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel` | Покреће bash команду у изолованом окружењу сесије и враћа stdout, stderr и излазни код. Дуга команда враћа `job_id` помоћу ког можете да наставите са чекањем. |
| `read_file` | `path`*, `session_id`, `project_id`, `ref`, `offset`, `limit` | Чита датотеку из изолованог окружења сесије или из git репозиторијума пројекта на `ref`. Слике се враћају као слике. |
| `write_file` | `session_id`*, `path`*, `content`*, `encoding` | Записује датотеку у изоловано окружење сесије и креира њене надређене директоријуме. `encoding` је `utf8` (подразумевано) или `base64`. |
| `list_files` | `path`, `session_id`, `project_id`, `ref`, `offset` | Наводи један директоријум из изолованог окружења сесије или све датотеке у репозиторијуму пројекта испод задате путање. |
| `read_skill` | `name`, `file`, `project_id` | Наводи водиче платформе Beeuni или враћа један водич (`name`) или једну од његових референтних датотека (`file`). Уз `project_id`, најпре се наводе вештине самог пројекта, а `name` за вештину пројекта враћа њен `SKILL.md` и путање до њених референтних датотека. |
| `list_connectors` | `project_id`*, `connector` | Наводи конекторе пројекта: slug, добављача, да ли је сваки `connected` (сада доступан за коришћење), број радњи и налоге. Уз `connector`, детаљно наводи налоге тог конектора. |
| `search_connector_actions` | `project_id`*, `query`, `connector`, `limit` | Проналази радње конектора према намени. Враћа `tool` (`<connector>.<action>`), `risk` и кратак опис. Никада не враћа шеме. |
| `describe_connector_action` | `project_id`*, `tool`* | Враћа улазну JSON шему, ниво ризика и опис једне радње. |
| `call_connector` | `project_id`*, `tool`*, `args`, `account`, `reason` | Покреће радњу у ваше име. Враћа податке и `account` који ју је покренуо, резултат `pending_approval` са везом за одобрење или одбијање са разлогом. |
| `upload_connector_attachment` | `project_id`*, `connector`*, `filename`*, `content_base64` или `session_id` + `path` | Поставља датотеку и враћа референцу `{"$beeuni_attachment": "<id>"}` коју треба унети у `args`. |
| `connect_connector` | `project_id`*, `connector`*, `owner`, `label` | Враћа везу коју особа отвара да би повезала налог конектора. |
| `search_connector_apps` | `project_id`*, `query`*, `limit`, `cursor` | Претражује каталог управљаних апликација из ког се може додати конектор. |
| `add_connector` | `project_id`*, `app` или `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url` | Одмах додаје конектор у пројекат (потврђује измену у `beeuni.yaml` на `main`, а затим синхронизује). |
| `remove_connector` | `project_id`*, `connector`* | Уклања конектор из пројекта. |
| `beeuni` | `args`*, `project_id`, `session_id` | Покреће стварни CLI за `beeuni` у ваше име и враћа `exit_code`, `stdout` (или `json` за излаз `--json`) и `stderr`. Погледајте [Покретање било које CLI команде](#run-any-cli-command). |
| `search_api` | `query`*, `limit` | Претражује Beeuni API руте према кључној речи. |
| `describe_api` | `method`*, `path`* | Враћа параметре, тело захтева и шему одговора једне руте. |
| `call_api` | `method`*, `path`*, `project_id`, `query`, `body` | Позива било коју руту `/v1/` у ваше име. `project_id` попуњава `{projectId}` у путањи. |

`search_api`, `describe_api` и `call_api` покривају све што могу веб апликација и
[CLI](/docs/sr/cli), јер су обе клијенти истог API-ја. `call_api`
одбија `/v1/oauth/*` и сваку путању која води до MCP крајње тачке. Сами попуните све
остале `{placeholder}` у путањи. Сваки позив користи исту
ауторизацију и ревизијски траг као захтев из веб апликације. Ревизијски траг бележи сваки
позив са `credential_kind: "oauth_app"` и називом повезане апликације, јер
API бележи акредитив који је користио за аутентификацију, а не ознаку коју шаље клијент.

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

### Покретање било које CLI команде

Алат `beeuni` покреће стварни CLI за [`beeuni`](/docs/sr/cli) у ваше име. Све CLI
команде раде преко њега, тако да MCP сервер има исти домет као терминал:
тајне, окидачи, `cr`, `review`, подсетници, агенти, модели, мрежни пролаз,
добављачи, канали, изолована окружења, апликације, маркетплејс, датотеке, приступ,
улоге, дозволе, ревизијски траг, овлашћења, чланови, групе, токени, обрачун, пројекти,
сесије и `system-skills`. Један алат замењује око 200 алата за подкоманде,
који би премашили ограничење броја алата у клијентима као што је Cursor.

`args` представља argv низ после `beeuni`, са по једним елементом низа за сваки аргумент. То никада није
командна линија љуске.

```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"] } }
```

- Откривајте помоћу `["--help"]` и `["<group>", "--help"]`. Додајте `--json` у
  излаз који рашчлањујете.
- `project_id` задаје пројекат за команду која је везана за пројекат. `session_id` задаје
  сесију за команду која делује на њу.
- Резултат је JSON: `exit_code`, `stdout`, `stderr`. Уз `--json`,
  излаз команде стиже као JSON вредност у `json` уместо у `stdout`. Излаз који не може да стане бива скраћен и означен са `truncated`; скраћени JSON није важећи JSON, зато сузите опсег команде. Ненулти `exit_code`
  представља MCP грешку. Сваки ток се скраћује на 24.000 (stdout) и 8.000 (stderr)
  знакова, а резултат то наводи у `truncated`.
- Команда која ради дуже од отприлике 45 секунди се прекида. Резултат садржи
  `timed_out`.
- Сервер истовремено покреће највише 4 CLI команде. Пети позив враћа
  `Busy`: покушајте поново.
- Сесије, датотеке у изолованом окружењу и конектори имају наменске алате
  (`start_session`, `run_command`, `read_file`, `call_connector`). Дајте им предност.

CLI се покреће на серверу помоћу вашег токена и приступа овом API-ју. Не добија
акредитиве сервера: његово окружење садржи само ваш токен, URL API-ја,
ИД-ове пројекта и сесије, као и празан привремени кућни директоријум и радни директоријум.
Сервер уклања оба директоријума након команде. Ауторизацију и ревизијски траг обезбеђује
API: токен спољног корисника добија исто `403` као и из терминала.

Ове команде се одбијају пре покретања. Грешка наводи разлог и
алтернативу.

| Команда | Зашто | Користите уместо тога |
| --- | --- | --- |
| било која заставица `--host` или `--host=`, `hosts` | Усмерава CLI на други сервер и тамо би послала ваш токен. | Овај сервер већ делује у ваше име. |
| `login`, `logout` | Пријављивање у прегледачу и сачувани токени. | Пријављени сте преко MCP везе. |
| `init`, `ship`, `deploy` | Читање или писање у локални директоријум. | `run_command` у изолованом окружењу сесије, где се изворни код налази. |
| `tools` | Чита и уређује локални `beeuni.yaml`, а сервер нема преузету копију пројекта. | `run_command` у изолованом окружењу сесије: тамо покрените `beeuni tools ls`. |
| `apps deploy` | Поставља локални директоријум, а сервер га нема. | `run_command` у изолованом окружењу сесије: тамо покрените `beeuni apps deploy <path>`. |
| `env pull`, `env push` | Уписује или чита локалну датотеку. | `secrets ls`, `secrets set KEY=value`. |
| `token`, `whoami --token-only` | Приказује сирови приступни токен. | `whoami --json`. |
| `update`, `uninstall` | Мења машину на којој се CLI покреће. | Нема га. |
| `tui`, `t`, `connect`, `attach`, `sessions connect|shell|forward` | Захтевају интерактивни терминал. | `start_session`, `send_message`, `read_session`, `run_command`. |
| `chat` и `sessions chat` без `--prompt` | Отварају интерактивно ћаскање. | `start_session`, `send_message` или додајте `--prompt "<text>"`. |

Ревизија бележи CLI команду са истим акредитивом као и сваки други позив
на вези (`credential_kind: "oauth_app"`). Не може да разликује алатку `beeuni` од алатке
`call_api`: обе приступају API-ју помоћу вашег токена.

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

### Вештине пројекта

`read_skill` са `project_id` наводи сопствене вештине пројекта (`skills/<slug>/SKILL.md`
датотеке спремишта или застарели `.beeuni/opencode/skills/`) пре водича платформе. Проследите
назив вештине `name` да бисте прочитали њен `SKILL.md` и путање њених референтних датотека, а `file` да бисте прочитали једну референцу. Видите вештине које ваша улога и додељене дозволе дозвољавају.

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

### Користите своје конекторе

Алати конектора су [`beeuni connectors`](/docs/sr/connect/connectors) CLI као MCP
алати. Позивају исте API руте као CLI и SDK, па се политика конектора, одобрење и ревизија понашају исто на свим површинама.

1. `list_connectors` приказује шта је повезано. Конектор са
   `connected: false` не може да покреће радње: позовите `connect_connector`, отворите
   враћену везу, па поново излистајте конекторе.
2. `search_connector_actions` проналази радњу према намери, на пример
   `send an email`. `describe_connector_action` враћа њене аргументе.
3. `call_connector` је покреће. Резултат наводи `account` који је извршио позив.
   Конектору са више налога и без подразумеваног налога потребан је `account`.
4. Проследите `reason` при упису чији су аргументи само идентификатори (`send_draft`,
   брисање према идентификатору). Одобравалац га види поред стварних аргумената.

Политика може да задржи позив ради одобрења. `call_connector` затим враћа
`status: "pending_approval"` са `approval_url`. Особа га отвара и одобрава. Поново позовите исти алат,
са истим аргументима и налогом у року од 15 минута: одобрени позив се извршава једном. Одбијање `policy_block` је коначно.

Резултат дужи од приближно 40.000 знакова враћа се као означени преглед
(`data_truncated`). Сузите аргументе и позовите поново. Да бисте приложили датотеку,
припремите је помоћу `upload_connector_attachment` и ставите враћену референцу у
`args`. Конектори са добављачем `composio` не прихватају референце прилога.

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

### Величина резултата и пагинација

- Резултат алата се скраћује на 60.000 знакова и завршава се са
  `…[truncated at 60000 chars]`.
- `read_file` враћа дугачку текстуалну датотеку у страницама од највише приближно 50.000
  знакова. Скраћени резултат завршава се са `offset` који га наставља. `offset`
  прескаче редове, а `limit` ограничава број враћених редова. Бинарна датотека се не
  враћа као текст: прочитајте је помоћу `run_command`.
- `list_files` на исти начин скраћује дугачку листу. Проследите `offset` који наводи.
- `list_sessions` враћа `next_cursor` када постоји још сесија. Вратите га назад
  као `cursor`.
- `read_session` враћа најновије поруке `limit`. Скраћује сваки улаз и излаз алата,
  а избацује најстарије поруке када резултат не може да стане (`omitted_older`). `last_turn_error`
  наводи неуспешан потез.
- Један MCP захтев добија одговор у року од 55 секунди. `read_session` са
  `wait_seconds` и изоловано окружење које се још покреће оба се заустављају пре тога:
  позовите поново.

<a id="sandboxes"></a>

### Изолована окружења

`run_command`, `read_file`, `write_file` и `list_files` са `session_id`
приступају активном изолованом окружењу сесије, на исти начин као веб терминал и панел датотека. Релативне путање се разрешавају испод `/workspace`, git преузете копије сесије. Заустављено изоловано окружење покреће се при првом позиву. CLI `beeuni` у изолованом окружењу пријављен је као сесија. Са `project_id` и без `session_id`, `read_file` и `list_files` читају git спремиште пројекта и не покрећу изоловано окружење.

Команда може да се извршава минутима. Један позив алата чека приближно 50 секунди. Ако команда и тада још ради, `run_command` враћа `status: running`, `job_id` и дотадашњи излаз. Позовите `run_command` са тим `job_id` да бисте наставили чекање или са `cancel: true` да бисте је зауставили. `timeout_seconds` (подразумевано 600, максимум 86400) зауставља команду која предуго ради, са излазним кодом `124`. Излаз се чува у `~/.cache/beeuni-mcp/jobs/<job_id>/` у изолованом окружењу; резултат алата приказује последњих 24.000 бајтова сваког тока. Изоловано окружење које се заустави повлачи са собом и команде које се у њему извршавају.

Сервер је без стања: одговара на `POST` помоћу JSON-а, а на `GET` и `DELETE` помоћу `405`.