Guides

How to set up an MCP server in Claude Code

Add remote and local MCP servers to Claude Code, pick the right scope, sign in with OAuth, and fix the connections that do not come up.

5 min read

The Model Context Protocol (MCP) is how Claude Code reaches tools outside your terminal: an issue tracker, a database, a deploy system, or a workflow platform like OutcomeCI. You add a server once, sign in, and its tools are available in every session where that server is in scope.

This guide uses the OutcomeCI MCP server as the running example. The same commands work for any remote MCP server; swap in its name and URL.

What you need

  • Claude Code installed. Check with claude --version.
  • The server's URL, and an account with the service behind it.
  • For OutcomeCI, an OutcomeCI account with access to a workspace.

Remote or local

MCP servers reach Claude Code in one of two ways:

Transport Where the server runs Use it for
http On the provider's infrastructure, at a URL Hosted services: most SaaS MCP servers, including OutcomeCI
stdio On your machine, as a process Claude Code starts Local tools, or servers distributed as an npm or Python package

Prefer http whenever a provider offers it. There is nothing to install or keep up to date, and sign-in happens in your browser with OAuth instead of an API key sitting in a config file.

Add a remote server

Run claude mcp add with --transport http, a name, and the URL:

claude mcp add --transport http outcomeci https://api.outcomeci.com/v1/mcp

The name is yours to choose. It is how the server appears in /mcp and in tool names, so keep it short and recognizable.

Choose a scope

--scope decides who sees the server and where it is stored:

Scope Available in Stored in
local (default) This project, for you only Your user config, keyed to the project
project This project, for everyone who clones it .mcp.json in the repository
user Every project on your machine Your user config

To have a server everywhere you work, add it at user scope:

claude mcp add --transport http --scope user outcomeci https://api.outcomeci.com/v1/mcp

To share a server with your team, add it at project scope and commit the file it writes:

claude mcp add --transport http --scope project outcomeci https://api.outcomeci.com/v1/mcp
{
  "mcpServers": {
    "outcomeci": {
      "type": "http",
      "url": "https://api.outcomeci.com/v1/mcp"
    }
  }
}

The file holds no credentials. Each teammate approves the server the first time Claude Code sees it, then signs in with their own account.

Sign in

A server that uses OAuth needs one sign-in before its tools load. Start it from your terminal:

claude mcp login outcomeci

Or from inside a session: run /mcp, select the server, and choose Authenticate.

Either way, your browser opens the provider's sign-in page. For OutcomeCI:

  1. Sign in to OutcomeCI if prompted.
  2. Select the workspace you want Claude Code to help configure.
  3. Review the requested access and select Allow access.
  4. Return to your terminal.

Claude Code stores the token and refreshes it as needed. To sign out, run claude mcp logout outcomeci.

Check the connection

List your servers and their status:

claude mcp list

A connected server shows as healthy. For more detail on one server, including its scope and URL:

claude mcp get outcomeci

Inside a session, /mcp shows each server, whether it is connected, and the tools it provides.

Put it to work

With the OutcomeCI server connected, describe the workflow you want and let Claude Code build it with you:

Help me create an OutcomeCI workflow that takes a feature request from Slack, discusses a plan with the requester, waits for their approval, and opens a pull request in the agreed repository. Show me the workflow before publishing it.

Claude Code can read the workflow format, inspect your existing workflows, and create or update them within the access you approved. When a workflow needs a credential, OutcomeCI gives you a browser form for it, so the value goes into your Vault and never passes through the conversation.

Add a local server

For a server that runs on your machine, put the command after --, and pass any environment variables it needs with -e:

claude mcp add my-server -e API_KEY=your-key -- npx -y my-mcp-server

Everything after -- is the command Claude Code runs to start the server. The -e values are saved in your config, so use a scope that keeps them out of the repository.

Run your workflows with Claude Code

This guide connects Claude Code to OutcomeCI so it can build workflows with you. To have OutcomeCI run those workflows with Claude Code on your Claude subscription, see Run OutcomeCI workflows with Claude Code.

Troubleshooting

The server shows as pending approval. Servers from a project's .mcp.json stay disconnected until you approve them. Run /mcp in a session to approve it. To revisit an earlier choice, run claude mcp reset-project-choices.

Authentication fails or never opens a browser. Confirm the URL is complete. For OutcomeCI it ends in /v1/mcp. Then run claude mcp login outcomeci again.

You picked the wrong workspace. Run claude mcp logout outcomeci, then sign in again and choose the right one.

The server is listed twice. The same name can exist in more than one scope. claude mcp get outcomeci shows which one is in use; remove the extra with claude mcp remove outcomeci --scope <scope>.

Next steps