← Back to the blog

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.

Equipo HilbanaProducto

Claude Code · MCP · Tutorial

How to Connect an MCP Server to Claude Code (With Hilbana as the Example)

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

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

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.

← Back to the blog