Claude Code · Connect, verify, repair

Claude Code MCP Tutorial: Setup, Examples & Troubleshooting

A connection command is only the beginning. Learn what each setup choice means, what evidence proves the connection works, and how to repair a mistake without giving away more access.

Free guide and three-check browser lab. No account, API key, installation, or payment required for the lab.

Try the free setup lab →

Reviewed September 8, 2026 · Independent ClaudeQuest learning material

How do you connect MCP to Claude Code?

Add the server with the transport it supports, inspect the saved definition, then check its runtime status and tools. For a hosted HTTP service, the basic pattern is:

claude mcp add --transport http <name> <url>

MCP connects Claude Code to tools and context supplied by a server. It does not make that server trustworthy or authorize every operation it exposes. Treat choosing a server and approving its actions as separate decisions.

Worked example: connect the public documentation server

To follow this on your own machine, you need an installed, working Claude Code environment and permission to change its configuration. The browser lab below is a simulation and needs neither.

Choose the intended project. Open its directory. This example uses the default local scope, so do not expect the definition to appear automatically in another project or on another computer.

Save the HTTP connection.

claude mcp add --transport http cq-docs https://code.claude.com/docs/mcp

Inspect before using. Run claude mcp get cq-docs to inspect the definition and claude mcp list to review configured servers. In Claude Code, use /mcp to inspect status and available tools.
Try a bounded task. Ask: “Find the documentation describing project-scoped MCP configuration. Use only documentation search or retrieval; do not submit feedback or change anything. Show the supporting passage.” Review the proposed tool and compare the result with the answer.

Share a definition, not someone’s credentials

For a reviewed, project-shared setup, use --scope project. Its definition belongs in the repository-root .mcp.json, not inside .claude/. The relevant HTTP entry looks like this:

{
  "mcpServers": {
    "cq-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

Review the file diff before committing. Never commit a personal configuration file wholesale to make a teammate’s setup work. Sharing a server definition does not share authentication or approval to access private services.

Imagine two developers reviewing the same issue. One has a personal connection and the other has none. The missing team definition is a configuration problem. If both have the definition but only one can read the issue, investigate identity and access instead. Changing transport randomly confuses two different failures.

HTTP versus stdio: find the actual mismatch

An HTTP connection targets a hosted endpoint. A stdio connection launches a local program. A URL placed in a definition marked stdio is not a local executable. For the documentation endpoint above, use type: "http" with its URL.

Reason from the intended service, not from whichever snippet is shortest. If a local server fails, inspect its launch command and paths; an absolute script path avoids depending on which directory started the process. Inspect unfamiliar software before installing or running it.

Evidence ladder: saved definition → connection established → intended tool available → approved operation succeeds → output supports the answer. A green signal on an earlier step does not prove the later steps.

Claude Code MCP not working? Diagnose the symptom.

The server is missing

Check the project and configuration scope before adding another copy. A user-scoped definition on your computer is not part of a teammate’s clone.

The connection fails

Compare transport and endpoint with the server’s instructions. For a local process, check the executable and launch path. Do not solve a network or process error by granting broader access.

Needs authentication

Use the service’s supported sign-in flow with your own approved account. A saved URL does not prove that account can access private data.

Connected, but the answer is wrong

Inspect which tool was called and what evidence it returned. Connection status is not an accuracy test. A plausible answer without a supporting result still needs review.

Keep a small troubleshooting note: intended operation, observed status, configuration scope, and the next single check. Omit tokens and private data. Retest after one change so you can tell which repair mattered.

FREE CONFIGURATION LAB · THREE CHECKS

Fix the setup before you trust the connection.

Choose a repair, see why it works, then tackle a different failure. All cases are simulated. Nothing is installed or connected, and no account or API key is needed.

Analytics are optional: with consent, we record lesson steps and numeric results, never credentials or configuration text. Privacy choices.

Turn the repair into a repeatable workflow

Now practise the surrounding skills: repository context, permission boundaries, implementation planning, and verification. The Claude Code learning route includes a free starting portion; paid continuation is an explicit choice, not a requirement to finish this lab.

Explore the Claude Code learning route →

Designing the server itself? Continue with MCP tool contracts and safe side effects. For a broader engineering routine, see Claude Code workflows.

Common setup questions

Does “Added” mean the server works?

No. It means the configuration was saved. Verify the connection, inspect the tools, and test an approved operation separately.

Should I turn off permissions to fix a connection?

No. Identify whether the failure concerns transport, process launch, network access, scope, or authentication. Broadening authority is not a generic connection repair.

Will this lab configure my machine or certify my skills?

No. It runs original, simulated checks in this page. It does not access your machine or retain your answers after reload. The feedback identifies errors in these three checks, not job or exam readiness.