MCP and events

Reference

MCP 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

WhatValue
Endpointhttps://volobox.example.com/mcp
TransportStreamable HTTP. The client sends its JSON-RPC requests with POST.
Server namevolobox
AuthenticationAuthorization: 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

ModeThe client sendsActs asReaches
TokenA bearer header with a personal access token (vbpt_...), an integration app's client secret (vbox_...) or an OAuth access tokenThe token's owner, or the appThe token's or the app's action groups
Sign-inNothing: the client signs the person in itselfThe person who signed inEvery action group the person can use

Token mode, as an mcpServers entry:

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

Sign-in mode is the URL alone:

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"]
}
FieldRule
redirect_urisRequired, 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_nameOptional. 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"
}
ErrorStatusMeaning
invalid_client_metadata400The body is not a JSON client registration.
invalid_redirect_uri400No redirect address, too many, or one that breaks the rules above.
too_many_requests429Registrations 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:

KindNamesWhat they are
Connectionvolobox_get_connectionWho the connection acts as and which groups it can use. Always listed.
Curatedvolobox_get_agenda, volobox_list_project_tasks and othersCommon reads and writes with model-friendly inputs. Listed for the groups the connection can use.
One per actionvolobox_ plus the operation idEvery public API action of the groups the connection can use.
Catalogvolobox_list_actions, volobox_describe_action, volobox_read_action, volobox_call_actionFind, 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:

FieldMeaning
actsAsperson, or integrationClient for an app's own secret.
via.kindHow 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.clientIdThe integration app's client id, when there is one.
userNameThe user name of the person the connection acts as; null for an app's secret.
actionsEvery action group with id, label, usable, and when it is not usable a reason: notOnToken, notGrantedAtSignIn, notSelectedForApp, needsPersonalSignIn or notGranted.
noteWhat 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.

Catalog tools

ToolInputWhat it does
volobox_list_actionsgroup, 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_actionidOne 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_actionid, params, queryRuns a GET action.
volobox_call_actionid, params, query, bodyRuns 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

ToolGroupWhat it does
volobox_get_agendaagendaLists the signed-in person's agenda items. Dates are yyyy-MM-dd.
volobox_get_agenda_itemagendaGets one agenda item by id.
volobox_create_agenda_itemagendaCreates an agenda item for the signed-in person.
volobox_update_agenda_itemagendaReplaces an agenda item's fields. Read it first and send every field back: a field left out is reset.
volobox_delete_agenda_itemagendaDeletes an agenda item.
volobox_set_agenda_item_statusagendaSets an agenda item's status.
volobox_get_my_profilepeopleGets the signed-in person's profile.
volobox_get_team_directorypeopleLists the people in the workspace directory.
volobox_list_my_projectsprojectsLists the projects the signed-in person belongs to.
volobox_get_project_by_idprojectsGets a project by id.
volobox_list_project_tasksprojectsLists the tasks of a project.
volobox_get_task_by_keyprojectsGets a task by its key, such as VBX-42: the project slug and the task number.
volobox_create_project_taskprojectsCreates a task in a project.
volobox_list_my_conversationsconversationsLists the chats the signed-in person can open.
volobox_get_conversationconversationsGets one chat by id.
volobox_list_conversation_messagesconversationsLists the messages of a chat.
volobox_get_pollconversationsGets 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_meetingsmeetingsLists meetings. Listing a meeting does not grant access to its details or to joining it.
volobox_get_meetingmeetingsGets a meeting by id.
volobox_list_file_entriesfilesLists the file entries the signed-in person can open.
volobox_get_file_entryfilesGets a file entry by id.
volobox_list_alertsfilesLists the signed-in person's alerts, newest first, active ones by default.
volobox_get_alertfilesGets one of the signed-in person's alerts by id.
volobox_acknowledge_alertfilesAcknowledges an active alert for everyone it reaches. It does not fix the condition.
volobox_export_audit_logauditExports 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.