Connect an assistant
Use your Hub's knowledge and tools from Claude Code, Claude or another MCP client, signed in as yourself and limited to the tools you may use.
You will connect Claude Code to a running Hub, allow the connection and ask a question it answers from the Hub's knowledge. Then you will see how to share the same Hub with your team, with Claude on the web and with other MCP clients.
The assistant brings its own model and subscription. The Hub supplies its instructions, knowledge and the tools the signed-in person may use, under the same access rules as chat.
Video lesson 8 · 2:55Your own Claude, connected through MCPConnect an assistant to your hub with your own identity.
What you need
- A Hub you can start. The quickstart creates
my-hubin about five minutes. - Claude Code (opens in a new tab) on the same machine, or another MCP client that supports OAuth sign-in. See other MCP clients.
- For anyone other than you: sign-in turned on and a public HTTPS address. See share it with your team.
Start the Hub
hubzoid run my-hubWhen the Hub is ready, hubzoid run prints the line that connects Claude Code:
✓ Hubzoid is ready: http://127.0.0.1:3080 (local mode, sign-in off)
Connect Claude Code: claude mcp add --transport http my-hub http://127.0.0.1:3080/mcpWhere the server name comes from
The server name, my-hub here, comes from the Hub folder's name, or from name: in the Hub's AGENTS.md when it sets one.
Add the Hub to Claude Code
Paste the line hubzoid run printed into a second terminal:
claude mcp add --transport http my-hub http://127.0.0.1:3080/mcpNo key or header goes into Claude Code's configuration. You authorize the connection in the next step.
Allow the connection
Start Claude Code, run /mcp, choose my-hub and authenticate.
Your browser opens Hubzoid. With sign-in on, Hubzoid asks you to sign in first. On your laptop sign-in is off and you are the Hub's owner, so you go straight to the consent page.
The consent page says which assistant wants to use which agent and which account you are signed in as. It lists what the connection allows: reading the agent's knowledge and files, and using the tools your access allows, including ones that make changes. Choose Allow connection and return to Claude Code.
Ask something
List the tools available from my-hub, then use them to tell me our refund window.Claude Code lists the Hub's tools, such as read_knowledge and grep_data, reads knowledge/house-rules.md and answers from it. The reasoning runs on Claude Code's own model. The Hub only runs the tools.
Connect other assistants
Claude on the web and desktop
Claude reaches the server from the internet, so the Hub needs a public HTTPS address first. See share it with your team.
- In Claude, open Customize, then Connectors, select + and Add custom connector.
- Enter a name and the full public MCP address, such as
https://hub.example.com/mcp. - Leave the advanced client ID and client secret empty. Hubzoid registers the client itself.
- Add the connector, connect, sign in to Hubzoid and choose Allow connection.
An organization administrator may need to allow custom connectors first. Menu labels depend on your Claude plan and version.
Other MCP clients
Other clients, such as Codex or Cursor, can connect when they meet every requirement below. Their setup is in their own documentation.
Every requirement a client must meet
| Requirement | Value |
|---|---|
| Transport | Streamable HTTP. Each JSON-RPC message is one POST. The server is stateless. |
| Address | https://<host>/mcp, or https://<host>/b/<hub>/mcp with several Hubs |
| Sign-in | OAuth authorization code flow with PKCE (S256), found from the WWW-Authenticate header of a 401 |
| Client registration | Dynamic registration as a public client, with no client secret. Redirect addresses use HTTPS, or HTTP on a loopback address such as localhost. |
| Resource | The resource parameter set to the exact MCP address |
| Scope | hub:access |
A client that can only send a fixed API key or header cannot connect. Hubzoid's own protocol tests run locally, so confirm one real sign-in with each client against your deployment before you roll it out.
Share it with your team
A Hub that teammates reach needs sign-in on and a public address. MCP then turns on by itself: hubzoid run serves it at <address>/mcp whenever the public address (HUBZOID_PUBLIC_URL) is HTTPS or on this computer. To set it yourself, put both values in the Hub's .env and restart:
MCP_SERVER=true
MCP_PUBLIC_URL=https://hub.example.com/mcpHow MCP_SERVER and MCP_PUBLIC_URL behave
MCP_SERVERandMCP_PUBLIC_URLin the Hub's.envalways win.MCP_SERVER=falseturns MCP off.MCP_PUBLIC_URLis the exact public address of the endpoint, ending in/mcpwith no trailing slash, on HTTPS, or HTTP only on this computer.- Connections are tied to that address. Changing it means everyone connects again.
- With several Hubs behind a gateway, each Hub turns MCP on in its own
.envand gets its own address,https://<host>/b/<hub>/mcp.
Each teammate then adds the shared address once and authenticates in /mcp as above:
claude mcp add --transport http --scope user my-hub https://hub.example.com/mcpBehind your own reverse proxy
The built-in public port routes everything MCP sign-in needs. A reverse proxy of your own must forward the MCP and sign-in paths to the Hub.
Every path to forward, with several Hubs too
A reverse proxy of your own must forward /mcp, /mcp/oauth/*, /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server/mcp/oauth to the Hub's bridge, along with /auth and /api/auth/* for sign-in. With several Hubs the same paths carry /b/<hub>: remove that prefix from the /mcp paths and keep the /.well-known/ paths whole.
Check discovery from outside before anyone connects. Both must return JSON that names your public address, not an HTML page:
curl -fsS https://hub.example.com/.well-known/oauth-protected-resource/mcp
curl -fsS https://hub.example.com/.well-known/oauth-authorization-server/mcp/oauthLimits, logging and the full OAuth route list
Apply your usual request size and rate limits, especially to /mcp/oauth/register and the authorization endpoint. Keep Authorization headers, cookies and token requests out of your logs. Every OAuth route is listed in the HTTP endpoints reference.
Decide who may connect
Signing in proves who someone is. The Use this agent grant (use_hub) decides whether they may use this Hub, over MCP exactly as in chat. Someone without it sees "Hub access needed" on the consent page and never sees a tool name.
Grant it to named people in Settings → Agents → the agent → Access. Use Add user for someone new, or Edit access on someone already listed.
Or grant it from the command line:
hubzoid grant priya@example.com use_hub ./my-hubOther ways access is granted, and what is no longer read
Granting any tool permission grants use_hub too. Chat app groups grant nothing, and MCP_ACCESS_GROUP is no longer read: hubzoid doctor warns while it is set. If the access store cannot be read, the call is refused rather than let through. The full Access editor is in restrict tools.
How it works
Chat: the Hub runs the model
The Hub agent reasons with the model set for the Hub and calls tools until it can answer.
Person
Web app, Slack or the API
Bridge
/v1Checks who is asking
Runtime
Runs the agent
Model
Reasons and asks for tools
Tools
Run in the bridge
MCP: the assistant brings its own model
The assistant does the reasoning. The Hub checks the access token, lists the tools this person may use and runs the ones called. A tool call runs no agent and keeps no conversation. Only a workflow offered as a tool can call the Hub model, inside its own run.
Assistant
With its own model
Bridge
/mcpChecks the token and access
Runtime
Not used
Model
Only inside a workflow run
Tools
Results go back to the assistant
Every call is checked in code before a tool runs. The model is never the gate.
The five checks on every call, and why no conversation is kept
- Sign-in and consent. The client receives OAuth credentials issued by Hubzoid and never sees the person's password or session. An existing sign-in skips the form, never the consent.
- The token check. An unknown or expired token, a revoked connection, or an account that is deleted, replaced, blocked or awaiting approval gets
401, with OAuth discovery in theWWW-Authenticateheader. - The front door. The person must hold Use this agent in this Hub.
- The tool list and the guard. Tools the person may not use are left out of the list, and a gated tool checks the permission again when it is called.
- The audit record. Every restricted tool decision, allowed or denied, is stored with the person and the channel
mcp.
The connection keeps no conversation. The assistant holds its own history, and each call to the Hub stands alone.
What the assistant receives
Instructions
When the client connects, it receives the body of AGENTS.md, the same text the Hub's own agent follows. Clients that support server instructions, such as Claude Code, add them to the assistant's context.
Give MCP clients shorter instructions
If AGENTS.md holds guidance meant only for the Hub's own agent, or is long, give MCP clients a shorter version. mcp_instructions: wins when present:
---
name: My Hub
mcp_instructions: |
House rules for Kestrel & Oak, a home-goods shop.
Use read_knowledge for policies such as house-rules.
Use grep_data for the exports in raw_data/.
---
You are the team assistant for Kestrel & Oak. ...Tools
The assistant gets the same tools the chat agent uses, minus the ones that only make sense inside a chat.
- Offered: the knowledge, file, search and utility tools such as
read_knowledge,grep_dataandhttp_get, and yourtools_local/tools. - Offered to people who may use them: your
restricted/tools, and the workflow, Run for me and access tools granted in Settings. Each call is checked again. - Over MCP only:
agent_health,eval_statusandrecent_denials, read-only tools for people who manage access to the agent. - As skills: sub-agents arrive through
load_skill. The Hub does not run a second model for an MCP caller. - Not offered: chat-only tools such as
write_artifactandread_upload,remember,call_jev, and the tools of the Hub's own MCP servers and connectors.
Context cost, and the mcp restricted surface
The full list per channel is in built-in tools. Every tool schema costs context in every connected client, so keep the set focused. The mcp channel is in the default HUBZOID_RESTRICTED_SURFACES list, because each caller signs in as themselves. If you set that variable, keep mcp in it.
Manage connections
- Revoke. Each person lists and revokes their assistant connections at
/mcp/oauth/connections, or/b/<hub>/mcp/oauth/connectionswith several Hubs, after signing in. Revoke connection stops its tokens at once. It does not undo actions or remove data already shared with the assistant.
Token lifetimes, account changes and API keys
- Lifetime. One scope,
hub:access, covers reading context and running the tools the person's access allows. There is no read-only grant. Access tokens last up to 10 minutes. Refresh tokens and the consent last up to 30 days, and reusing an old refresh token revokes the connection. Client registrations expire after a year. - Account changes. Every call checks the account and its grants again. Deleting, replacing or blocking the account, or removing Use this agent, ends access on the next call. A grant changed in Settings applies on the next call, with no reconnect.
- Keys. API keys, including keys from
BRIDGE_API_KEYS, are never accepted at/mcp.
Test allowed and denied calls
Before handing the address to a team, check both sides of the door. A request without a token must be refused:
curl -si https://hub.example.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'The answer is 401 with a WWW-Authenticate header that points to OAuth discovery. Then connect as a person with access and as one without.
Every check and its expected result
| Check | Expected result |
|---|---|
No token, a made-up one, or a key from BRIDGE_API_KEYS | 401 |
| Sign-in as someone without Use this agent | "Hub access needed" on the consent page, and no connection |
| Sign-in as someone with access | The tools list shows the unrestricted tools |
| A restricted tool the person lacks | Missing from the tools list, and a call returns isError with an access denied message |
The connection revoked at /mcp/oauth/connections | 401 on the next call, until the person connects again |
What a refused call returns, and where to review decisions
A refused restricted tool answers with "isError": true and a message like this, and the attempt is recorded:
[access denied: 'ledger_read' requires the "Read ledger" (ledger) permission, which the current user does not have. This attempt was logged.]Review the decisions in Settings → Activity → Audit log → Tool decisions, with the channel filter set to mcp, or on the server:
hubzoid audit ./my-hub --deniedIf something goes wrong
| What you see | What to do |
|---|---|
hubzoid run prints no "Connect Claude Code" line | MCP is off. Remove MCP_SERVER=false from the Hub's .env, or set MCP_SERVER=true with an MCP_PUBLIC_URL, then restart. |
| "Hub access needed" on the consent page | Grant the person Use this agent on the agent's Access tab, then reconnect from the assistant. |
| "Connection expired" in the browser | Start connecting again from the assistant. |
Claude Code sends an old Authorization header or API key | Remove the old entry, for example claude mcp remove my-hub --scope user, then add it again without a header. |
Every call returns 401 after it worked | The connection was revoked, the account changed or MCP_PUBLIC_URL changed. Authenticate again in /mcp. |
| A tool is missing from the list | It is restricted and the person lacks its permission, or it is a chat-only tool. |
More problems and fixes
| What you see | What to do |
|---|---|
A discovery curl returns HTML | Your proxy does not forward the /.well-known/ paths to the Hub. |
| Claude on the web cannot reach the Hub | It needs a public HTTPS address that the internet can reach. |
Operational notes
The endpoint is stateless, so it works behind a load balancer and across bridge restarts.
Where tools run, and who pays for model calls
- MCP calls run the Hub's tools on the Hub's machine, with the Hub's own credentials. Keep the credentials a tool needs in
restricted/.env. The file-reading tools refuse therestricted/folder, so no caller can read it. - Tool and knowledge calls over MCP spend none of the Hub's model tokens. A workflow offered as a tool runs on the Hub, and any model call it makes is billed to the Hub like any other run.
Next steps
Restrict tools
Put a sensitive tool behind a permission before you share the Hub over MCP.
Chat inside your own app
Put the agent's chat in your own app, signed in by your app.
Agents and access
Grant Use this agent and tool permissions in Settings.
Several Hubs
Serve several Hubs, each with its own MCP address, behind one front door.