MCP Integrator Guide

Prerequisites

• An active qbit.me workspace.
• A workspace MCP key obtained from Account > MCP servers in the dashboard.
• An MCP client that can send JSON-RPC 2.0 requests over HTTPS.

Only workspace owners can regenerate the managed MCP key. The complete key value is revealed once after regeneration; store it in a secret manager and never commit it to source control.

Endpoint and Authentication

Send MCP requests to:

https://app.qbit.me/api/mcp

Authenticate every request with the workspace MCP key header:

X-Qbit-Mcp-Key: <workspace-mcp-key>

Also send Content-Type: application/json on request bodies.

The X-Qbit-Mcp-Key header applies only to the MCP endpoint. It is not a general REST API credential: dashboard REST requests use the signed-in operator session, which is a separate auth contract.

Discover Tools

Start with the MCP initialize handshake required by your client, then call tools/list. Treat that live response as the source of truth — the server catalog evolves over time, and a copied catalog will go stale.

Example tools/list request body:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

The response lists each tool's name, description, and inputSchema. Use the exact name and inputSchema from that response in subsequent tools/call requests.

Call a Tool

Use the exact tool name and arguments returned by tools/list. The example below uses sessions.list, which takes no required arguments:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {"name": "sessions.list", "arguments": {}}
}

Other non-moat read tools that take empty arguments include devices.list, kanban.projects.list, and teams.list. Always confirm the current schema via tools/list before relying on any tool name or argument shape.

Connect qbit.me to Your MCP Server

So far this guide covers qbit.me as an MCP server — exposing workspace tools to an external MCP client. qbit.me also works in the other direction, as an MCP client: a workspace owner can connect an external MCP server and make its tools available to the agent on their appliance.

This matters if your product already exposes an MCP server. Your customer's qbit agent can call the tools on your server directly — no proxy code to write, no separate integration layer. The agent reaches your tools through the same MCP handshake it already uses.

How to connect

• In the qbit.me dashboard, open Account > MCP servers.
• Add a new MCP server with your endpoint URL.
• Choose the auth method your server expects — Bearer or a custom header — and enter the secret.
• qbit.me connects to your endpoint and discovers its tools via tools/list.
• Choose which of your tools to enable (optional). The enabled set is what your customer's agent sees.
• The tool list is delivered to the agent on the appliance. Your customer's agent can now call your tools in conversation.

How tool discovery and delivery work

When you add or refresh an MCP server, qbit.me performs a live tools/list request against your endpoint (with an 8-second timeout). On success, the discovered tools become available. If the endpoint is temporarily unreachable, qbit.me keeps the last known tool list so the configuration stays usable and refreshes on the next successful discovery.

Each MCP server row lets a workspace owner enable or disable individual tools. The chosen set — not the full catalog — is what gets delivered to the agent on the device. Tools you disable are simply not exposed to the agent, even though your server still serves them.

Auth and key safety

• Bearer — qbit.me sends Authorization: Bearer <secret> on every tool call.
• Header — qbit.me sends the secret under the header name you specify (for example, X-Api-Key).
• Your server's secret is stored as a protected value in qbit.me and shown only as a masked preview after creation.
• Scope your server's API key to the least privilege your customer's agent needs. The agent inherits exactly what your key allows.
• Rotate the key from the dashboard when exposure is suspected; the update pushes to the appliance on the next configuration refresh.

Workspace owners manage MCP servers; only owners can add, edit, or remove a third-party server connection.

Errors and Retries

• 401 — the credential is missing, invalid, or no longer active. Do not retry with the same key; regenerate it from the dashboard.
• 402 — the requested action requires the user to resolve account or payment state in qbit.me. Do not attempt to automate a payment flow from this guide.
• 429 — wait and retry with bounded exponential backoff and jitter.
• 5xx — retry idempotent reads with bounded backoff; surface persistent errors to the user.

Do not assume mutations are idempotent. Use only the idempotency behavior explicitly advertised by the relevant tool's contract.

Key Safety

• Keep MCP keys server-side. Never embed them in browser bundles, logs, prompts, or client-side code shipped to end users.
• Rotate the key immediately if exposure is suspected.
• Re-run tools/list after reconnecting or when cached schemas may be stale.
• Give each external system only the workspace access it needs. Prefer a dedicated workspace scope per integration over sharing a single key.

FAQ

Why is a tool missing? The current server catalog may not provide it. Check tools/list rather than relying on a copied catalog — tool availability reflects the workspace's current configuration.

Can I use the MCP key for normal REST endpoints? No. This guide documents the MCP endpoint. Dashboard REST authentication is a separate operator-session contract.

Does the catalog include every qbit.me capability? No. The MCP catalog exposes a bounded set of workspace tools. Capabilities not exposed via tools/list are not callable through this endpoint.

Ready to make your SaaS agent-native? Read the platform overview or get a qbit agent.