Developers

Guide

Connect 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-inPersonal token
What you put in the clientThe server URL aloneThe server URL and an Authorization header
What the client storesA sign-in it renews itselfThe token you pasted
What it reachesEvery action group you can useThe groups you chose for the token
Use it whenThe 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

  1. Add this server in your client's MCP settings:

    JSON
    {
      "mcpServers": {
        "volobox": {
          "url": "https://volobox.example.com/mcp"
        }
      }
    }
  2. Start or reload the server in your client. The client registers itself with Volobox and opens Volobox's sign-in page in your browser.

  3. Sign in with your Volobox account. With two-factor authentication on, the code is asked on the same page.

  4. 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

  1. 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.

  2. 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_..." }
        }
      }
    }
  3. 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).

The MCP server card in Personal Settings, API & MCP: the server address with Copy, and an example client configuration that sends a personal token as a bearer header.

Check that it works

  1. Ask the agent to call volobox_get_connection. It answers with:
    • userName: your Volobox user name.
    • via.kind: signIn for a sign-in, token for a personal token.
    • actions: every action group, each with usable set to true or false, and a reason when it is false.
  2. 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_getByAssignee or volobox_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

SymptomFix
The agent lists only volobox_get_connectionIt 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 notOnTokenA 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 browserThe client cannot sign in to remote MCP servers. Connect with a personal token.
The client accepts only a fixed tokenGive 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 againThe 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 workingThe 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 accessThat 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