MCP and events
ReferenceMCP server
The hosted Volobox MCP server: endpoint, transport, OAuth discovery and client registration, tool naming, catalog tools and curated tools.
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.
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:
{
"mcpServers": {
"volobox": {
"url": "https://volobox.example.com/mcp",
"headers": { "Authorization": "Bearer vbpt_..." }
}
}
}Sign-in mode is the URL alone:
{
"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/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:
{
"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):
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:
{
"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.getListbecomesvolobox_projects_projectTask_getList. - Description: the action's summary, followed by its method and route, such as
(GET /api/v1/project-task). - Hints: a
GETis marked read-only, aDELETEdestructive, and aPOSTorPUTa 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 singlebodyargument. Any other field is refused. - Values: an enum is its name (
"status": "Open"), a calendar day isyyyy-MM-dd, as in the API.
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 asvolobox_audit_auditLog_exportJsonl) and the catalog tools. - Without Audit log, the server lists only
volobox_get_connection, whosenotesays 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.