# MCP server

This page is the contract of the MCP server that Volobox hosts for outside AI agents: where it is, how a client authenticates or signs a person in, how its tools are named, and which tools it offers. To connect a client step by step, follow [Connect an MCP client](/docs/connect-mcp-client).

## Endpoint and transport

| What | Value |
| --- | --- |
| Endpoint | `https://volobox.example.com/mcp` |
| Transport | Streamable HTTP. The client sends its JSON-RPC requests with `POST`. |
| Server name | `volobox` |
| Authentication | `Authorization: Bearer ...` on every request. A browser's Volobox sign-in cookie is not accepted. |

The server tells the client, in its instructions, that its tools act as the connection's identity and that `volobox_get_connection` says who that is.

## Two ways to connect

| Mode | The client sends | Acts as | Reaches |
| --- | --- | --- | --- |
| Token | A bearer header with a personal access token (`vbpt_...`), an integration app's client secret (`vbox_...`) or an OAuth access token | The token's owner, or the app | The token's or the app's action groups |
| Sign-in | Nothing: the client signs the person in itself | The person who signed in | Every action group the person can use |

Token mode, as an `mcpServers` entry:

```json title="Token mode"
{
  "mcpServers": {
    "volobox": {
      "url": "https://volobox.example.com/mcp",
      "headers": { "Authorization": "Bearer vbpt_..." }
    }
  }
}
```

Sign-in mode is the URL alone:

```json title="Sign-in mode"
{
  "mcpServers": {
    "volobox": {
      "url": "https://volobox.example.com/mcp"
    }
  }
}
```

## OAuth discovery

A request without a bearer is answered `401` with a challenge that points at the server's protected resource metadata (RFC 9728):

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Volobox", resource_metadata="https://volobox.example.com/.well-known/oauth-protected-resource/mcp", scope="Volobox offline_access"
```

A request whose bearer is refused gets the same challenge with `error="invalid_token"` added.

The metadata at `/.well-known/oauth-protected-resource/mcp` needs no sign-in:

```json
{
  "resource": "https://volobox.example.com/mcp",
  "resource_name": "Volobox",
  "authorization_servers": ["https://volobox.example.com/"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["Volobox", "offline_access"]
}
```

The authorization server's discovery document names a `registration_endpoint` and lists `none` among the token endpoint's authentication methods, since a registered MCP client is public and redeems its code with PKCE alone. A `resource` parameter that names the MCP endpoint (RFC 8707) is accepted on the authorization and token requests.

## Dynamic client registration

An MCP client that signs a person in registers itself first (RFC 7591):

```http
POST /connect/register HTTP/1.1
Host: volobox.example.com
Content-Type: application/json

{
  "client_name": "Example Agent",
  "redirect_uris": ["http://127.0.0.1:33418/callback"]
}
```

| Field | Rule |
| --- | --- |
| `redirect_uris` | Required, 1 to 10 addresses. Each is `https://`, `http://` on a loopback address, or an app's own scheme (such as `cursor://` or `vscode://`). No fragment. Schemes a browser runs or reads itself (`javascript`, `data`, `file`, `blob`, `about` and the like) are refused. |
| `client_name` | Optional. Shown on the consent page. Control characters are dropped and it is cut at 128 characters; without one it reads "MCP sign-in". |

Whatever the request asks for, the client is registered as a public client that may only run the authorization code flow with PKCE and refresh its tokens. The answer is `201 Created`:

```json
{
  "client_id": "CLIENT_ID",
  "client_id_issued_at": 1794652800,
  "client_name": "Example Agent",
  "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "Volobox openid profile offline_access"
}
```

| Error | Status | Meaning |
| --- | --- | --- |
| `invalid_client_metadata` | `400` | The body is not a JSON client registration. |
| `invalid_redirect_uri` | `400` | No redirect address, too many, or one that breaks the rules above. |
| `too_many_requests` | `429` | Registrations are limited per address and in total. Try again later. |

Every sign-in through a registered client shows the person a consent page. The sign-in then acts as that person. With the standard settings it ends when it goes unused for about 14 days, or when the person logs its **OAuth** row out under **Account** > **Sessions**.

## Tools

The server lists only the tools the connection can use. There are four kinds:

| Kind | Names | What they are |
| --- | --- | --- |
| Connection | `volobox_get_connection` | Who the connection acts as and which groups it can use. Always listed. |
| Curated | `volobox_get_agenda`, `volobox_list_project_tasks` and others | Common reads and writes with model-friendly inputs. Listed for the groups the connection can use. |
| One per action | `volobox_` plus the operation id | Every public API action of the groups the connection can use. |
| Catalog | `volobox_list_actions`, `volobox_describe_action`, `volobox_read_action`, `volobox_call_action` | Find, describe and run any of those actions by operation id. |

### `volobox_get_connection`

Call it first, and again when a tool you expect is missing. It answers:

| Field | Meaning |
| --- | --- |
| `actsAs` | `person`, or `integrationClient` for an app's own secret. |
| `via.kind` | How the connection was made: `token` (a personal token), `app` (a person signed in through an integration app), `signIn` (the server's own sign-in), `secret` (an app's secret). |
| `via.clientId` | The integration app's client id, when there is one. |
| `userName` | The user name of the person the connection acts as; `null` for an app's secret. |
| `actions` | Every action group with `id`, `label`, `usable`, and when it is not usable a `reason`: `notOnToken`, `notGrantedAtSignIn`, `notSelectedForApp`, `needsPersonalSignIn` or `notGranted`. |
| `note` | What to do next, when the connection can use little or nothing. |

### Tools for each action

Every public action of a usable group is a tool of its own:

- **Name:** `volobox_` and the operation id with `.` replaced by `_`, at most 64 characters. `projects.projectTask.getList` becomes `volobox_projects_projectTask_getList`.
- **Description:** the action's summary, followed by its method and route, such as `(GET /api/v1/project-task)`.
- **Hints:** a `GET` is marked read-only, a `DELETE` destructive, and a `POST` or `PUT` a write.
- **Arguments:** one flat object. Route values are required; query parameters use camelCase names (`projectId`, `maxResultCount`); the body's properties sit beside them. A body that is not an object with properties, such as a list, is passed as a single `body` argument. Any other field is refused.
- **Values:** an enum is its name (`"status": "Open"`), a calendar day is `yyyy-MM-dd`, as in the [API](/docs/api-overview).

### Catalog tools

| Tool | Input | What it does |
| --- | --- | --- |
| `volobox_list_actions` | `group`, `search`, `cursor` (all optional) | Lists the actions the connection can call, 50 a page: `id` (the operation id), `group`, `method`, `route`, `summary`, `deprecated`, with `totalCount` and a `nextCursor` to pass as `cursor`. `search` matches a word in the id, route or summary. |
| `volobox_describe_action` | `id` | One action's method and route, each parameter with where it goes and its type, the body schema and the schema of the answer. |
| `volobox_read_action` | `id`, `params`, `query` | Runs a `GET` action. |
| `volobox_call_action` | `id`, `params`, `query`, `body` | Runs a `POST`, `PUT` or `DELETE` action. Describe it first. |

`params` holds the route values and `query` the query parameters, by name. A catalog tool or a per-action tool returns the action's refusal as `{ "ok": false, "status": ..., "error": ... }` in its answer, not as a tool error. A curated tool's refusal, and a call to a group the connection cannot use, is a tool error whose text names the tool and carries the error's code and message.

### Curated tools

| Tool | Group | What it does |
| --- | --- | --- |
| `volobox_get_agenda` | `agenda` | Lists the signed-in person's agenda items. Dates are `yyyy-MM-dd`. |
| `volobox_get_agenda_item` | `agenda` | Gets one agenda item by id. |
| `volobox_create_agenda_item` | `agenda` | Creates an agenda item for the signed-in person. |
| `volobox_update_agenda_item` | `agenda` | Replaces an agenda item's fields. Read it first and send every field back: a field left out is reset. |
| `volobox_delete_agenda_item` | `agenda` | Deletes an agenda item. |
| `volobox_set_agenda_item_status` | `agenda` | Sets an agenda item's status. |
| `volobox_get_my_profile` | `people` | Gets the signed-in person's profile. |
| `volobox_get_team_directory` | `people` | Lists the people in the workspace directory. |
| `volobox_list_my_projects` | `projects` | Lists the projects the signed-in person belongs to. |
| `volobox_get_project_by_id` | `projects` | Gets a project by id. |
| `volobox_list_project_tasks` | `projects` | Lists the tasks of a project. |
| `volobox_get_task_by_key` | `projects` | Gets a task by its key, such as `VBX-42`: the project slug and the task number. |
| `volobox_create_project_task` | `projects` | Creates a task in a project. |
| `volobox_list_my_conversations` | `conversations` | Lists the chats the signed-in person can open. |
| `volobox_get_conversation` | `conversations` | Gets one chat by id. |
| `volobox_list_conversation_messages` | `conversations` | Lists the messages of a chat. |
| `volobox_get_poll` | `conversations` | Gets a poll asked in a chat: the question, the options, the counts the person may see and whether they answered. Never who voted. |
| `volobox_list_meetings` | `meetings` | Lists meetings. Listing a meeting does not grant access to its details or to joining it. |
| `volobox_get_meeting` | `meetings` | Gets a meeting by id. |
| `volobox_list_file_entries` | `files` | Lists the file entries the signed-in person can open. |
| `volobox_get_file_entry` | `files` | Gets a file entry by id. |
| `volobox_list_alerts` | `files` | Lists the signed-in person's alerts, newest first, active ones by default. |
| `volobox_get_alert` | `files` | Gets one of the signed-in person's alerts by id. |
| `volobox_acknowledge_alert` | `files` | Acknowledges an active alert for everyone it reaches. It does not fix the condition. |
| `volobox_export_audit_log` | `audit` | Exports a page of the organization audit log: `content` is NDJSON text, `nextCursor` the cursor for the next page or `null`. |

## What a client secret alone can do

An integration app's secret acts as the app, not as a person, so on this server it reaches only **Audit log**:

- When an administrator selected **Audit log** for the app, the server lists `volobox_get_connection`, `volobox_export_audit_log`, the tools of the audit log's actions (such as `volobox_audit_auditLog_exportJsonl`) and the catalog tools.
- Without **Audit log**, the server lists only `volobox_get_connection`, whose `note` says how to connect as a person instead.

To read someone's agenda, projects or chats, connect as that person: with a personal access token, through an app people sign in through, or in sign-in mode.

## What an agent cannot do here

An agent connected to this server reads what the person behind it can read. Some writes stay a person's own and are refused: a reply a customer would see on a ticket, a write to a client's drive, and a write into the discussion of an app record whose app keeps agents out. An outside agent never adds a Volobox agent to a space, project, drive, file, chat or group, and never changes an agent's role there. An app's records themselves are not reachable over the API or MCP today; only a published record's discussion is, through the Conversations group.

## Related

- [Connect an MCP client](/docs/connect-mcp-client)
- [API overview](/docs/api-overview)
- [Build an OAuth integration](/docs/oauth-integration)
- [API, MCP and webhooks](/docs/api-and-mcp)
