Developers
GuideConnect an MCP client
Connect an MCP client that speaks streamable HTTP to the hosted Volobox MCP server, by signing in or with a personal access token.
At the end of this guide your AI client (any MCP client that connects to remote servers over streamable HTTP) lists Volobox's tools and calls them as you: it reads your agenda, projects, chats, meetings and files, and creates tasks and agenda items, within what you can open yourself. Any member of a workspace can connect a client; no administrator is needed.
Before you begin
- A Volobox account in your workspace, and its address (this guide uses
https://volobox.example.com). - An MCP client that connects to remote servers over streamable HTTP.
- To connect with a token instead of a sign-in: a personal access token. Make your first API call shows how to create one.
Choose how the client connects
| Sign-in | Personal token | |
|---|---|---|
| What you put in the client | The server URL alone | The server URL and an Authorization header |
| What the client stores | A sign-in it renews itself | The token you pasted |
| What it reaches | Every action group you can use | The groups you chose for the token |
| Use it when | The client can sign in to remote MCP servers (it opens a browser) | The client accepts only a fixed header, or runs where nobody can sign in |
Connect with a sign-in
-
Add this server in your client's MCP settings:
JSON{ "mcpServers": { "volobox": { "url": "https://volobox.example.com/mcp" } } } -
Start or reload the server in your client. The client registers itself with Volobox and opens Volobox's sign-in page in your browser.
-
Sign in with your Volobox account. With two-factor authentication on, the code is asked on the same page.
-
Approve the client on the consent page Volobox shows next. The browser hands the sign-in back to the client.
Connect with a personal token
-
In Volobox, open your menu, choose Settings, open API & MCP, and create a token under Personal tokens with the action groups the agent needs. Copy it.
-
Add this server in your client's MCP settings, with your token in place of
vbpt_...:JSON{ "mcpServers": { "volobox": { "url": "https://volobox.example.com/mcp", "headers": { "Authorization": "Bearer vbpt_..." } } } } -
Start or reload the server in your client.
Warning
The token acts as you. Keep the file that holds it out of source control and off shared machines. If your client can read the header's value from an environment variable or a secret store, use that instead of pasting the token into the file.
Note
Clients name this setting differently: some need "type": "http" beside the URL, some use a servers key instead of mcpServers. Follow your client's documentation for remote servers. If yours does not use an mcpServers object, add a server named volobox where its documentation says remote HTTP servers go, with the same URL and, for a token, the same header. If it asks for a transport, choose HTTP (streamable HTTP).
Check that it works
- Ask the agent to call
volobox_get_connection. It answers with:userName: your Volobox user name.via.kind:signInfor a sign-in,tokenfor a personal token.actions: every action group, each withusableset totrueorfalse, and areasonwhen it isfalse.
- Ask for something you know is there, such as "List the tasks assigned to me in Volobox" or "What is on my agenda today?". The agent calls the matching tool, such as
volobox_projects_projectTask_getByAssigneeorvolobox_get_agenda, and answers from your workspace.
Beside the named tools, every public API action of your groups is a tool of its own (such as volobox_support_ticket_getList), and four catalog tools find and run them: volobox_list_actions, volobox_describe_action, volobox_read_action and volobox_call_action. The MCP server reference lists them all.
Troubleshooting
| Symptom | Fix |
|---|---|
The agent lists only volobox_get_connection | It is connected with an integration app's client secret, not as you. Use a personal token, or remove the Authorization header and connect again so it asks you to sign in. |
volobox_get_connection says a group is notOnToken | A token's groups are fixed when it is made. Create another token with that group and put it in the header. |
| The client says the server needs authorization but never opens a browser | The client cannot sign in to remote MCP servers. Connect with a personal token. |
| The client accepts only a fixed token | Give it a personal token. An integration app's secret is not you and cannot open your agenda, projects or chats. |
| The agent asks you to sign in again | The sign-in went unused for about 14 days, or it was logged out under Account > Sessions. Connect again the same way. |
| A token that worked stopped working | The token was revoked or expired, or your password or two-factor setting changed, which ends every personal token. Create a new one. |
| The agent says it cannot give an agent access | That is on purpose: an outside agent never adds a Volobox agent to a space, project, drive, file, chat or group, or changes an agent's role there. Do it yourself in Volobox. |
| The agent needs something the named tools do not cover (a document, a ticket, time off) | Ask it to use that action's own tool, or to call volobox_list_actions with the group (docs, support, calendar, ...) and then volobox_describe_action before it runs one. |
To disconnect a client, log its OAuth row out under Account > Sessions in your settings for a sign-in, or Revoke the token on API & MCP for a token.
Next steps
- MCP server: the tools, the catalog tools and how the sign-in works.
- API overview: the same actions over plain HTTP.
- Build an OAuth integration: register an app that signs people in.