# Connect an MCP client

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](/docs/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

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

![Personal Settings, API & MCP, MCP tab: the MCP server card with the server address and a copy button, and an example MCP client configuration that sends a personal token as a bearer header.](https://volobox.io/docs/images/mcp-connection.light.webp)

*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](/docs/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](/docs/mcp-server): the tools, the catalog tools and how the sign-in works.
- [API overview](/docs/api-overview): the same actions over plain HTTP.
- [Build an OAuth integration](/docs/oauth-integration): register an app that signs people in.
