How to Connect an MCP Server to Claude Code (With Hilbana as the Example)
How to add an MCP server to Claude Code: the three transports, the three scopes, sharing it with your team, OAuth, and a real example connecting Hilbana.
Claude Code · MCP · Tutorial

An MCP server is how Claude Code reaches a tool that is not on your machine: a task board, a database, a documentation site. Connecting one takes a single command, but three choices decide how it behaves: the transport, the scope and how it authenticates. This guide goes through them in that order, then uses Hilbana as a worked example.
The commands and behaviours below come from the Claude Code documentation on MCP, read on 2 November 2026. Claude Code changes quickly, so if something differs, trust claude mcp --help and the official docs.
1. Pick the transport
| Transport | Command | When |
|---|---|---|
| HTTP (recommended) | claude mcp add --transport http <name> <url> |
Any remote server |
| stdio | claude mcp add --transport stdio <name> -- <command> [args] |
A server that runs on your machine |
| SSE | claude mcp add --transport sse <name> <url> |
Only if the server offers nothing else: the docs mark it deprecated |
For stdio, the -- separates Claude’s own options from the server’s command. Anything after it goes to the server. Environment variables go with --env KEY=value, and a request header with --header "Name: value".
2. Pick the scope
The scope decides where the connection is stored and who gets it.
| Scope | Stored in | Shared with your team |
|---|---|---|
| local (default) | ~/.claude.json, under the project’s path |
No, only this project |
| project | .mcp.json in the project root |
Yes, through version control |
| user | ~/.claude.json |
No, but available in all your projects |
You choose it with --scope, for example claude mcp add --transport http shared-server --scope project https://example.com/mcp.
If the same server is defined in several places, Claude Code uses this order: local, project, user, then servers provided by plugins, then claude.ai connectors. The first match wins as a whole entry; fields are not merged.
Sharing with the team
A project-scoped server lives in a .mcp.json file you commit:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}
For safety, Claude Code asks for approval in an interactive session before using a project-scoped server. If you change your mind, claude mcp reset-project-choices clears those answers. Never put a secret in .mcp.json: it is in your repository.
3. Authenticate
Many remote servers use OAuth. The flow is simple: run /mcp inside Claude Code, pick the server, and follow the steps in your browser. Claude Code stores the tokens and refreshes them for you. From a shell, claude mcp login <name> and claude mcp logout <name> do the same.
If a server needs a key instead, pass it as a header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
Use that for a CI job or a server without OAuth, and keep the token in your local configuration, not in the repo.
4. Check it
claude mcp listshows your servers andclaude mcp get <name>shows one.- Inside Claude Code,
/mcpshows each server’s status and lets you authenticate. claude mcp remove <name>removes it. Removing a remote server deletes its stored tokens locally but does not revoke them: runclaude mcp logout <name>first if you want to revoke.
A real example: connecting Hilbana
Hilbana is a task board for teams whose AI agents take tasks, finish them and keep what they learned. It exposes an MCP server, so everything above applies. There are two ways to connect it.
Plain MCP, with OAuth. No key to copy:
claude mcp add --transport http hilbana https://app.hilbana.com/mcp
Then run /mcp in Claude Code and authenticate the hilbana server in your browser.
The plugin. It adds persistent memory with automatic hooks, per-task token accounting and /hilbana: commands on top of the MCP server. It needs Node 18 or later and an API key (format hil_…) created under Settings → Agents → API keys (admins only) in the workspace you work in:
/plugin marketplace add hilbana/claude-plugin
/plugin install hilbana@hilbana
Restart Claude Code, run /mcp, and you should see plugin_hilbana_hilbana connected. The full walkthrough, with the first work loop, is in the Hilbana + Claude Code guide and the plugin documentation.
What to watch out for
- Trust the server first. The Claude Code docs warn that servers which fetch external content can expose you to prompt injection. Connect only servers you trust.
- Big answers get cut. Claude Code warns when a tool’s output exceeds 10,000 tokens and limits it to 25,000 by default. You can change that with the
MAX_MCP_OUTPUT_TOKENSenvironment variable. - Slow servers.
MCP_TIMEOUTsets the startup timeout andMCP_TOOL_TIMEOUTthe time allowed for a tool call. 401errors. The key is incomplete, revoked or expired. Create a new one and paste it whole: Hilbana shows it only once.- Work lands in the wrong workspace. With an API key, the key’s workspace is the one used. Create the key in the workspace you mean.
You can try Hilbana for free: the Free plan does not expire and asks for no card.
The Claude Code behaviours in this article were read from code.claude.com/docs/en/mcp on 2 November 2026. The Hilbana steps come from our own guide.