Skip to content

8.3 Connecting Your First Server

Theory's done — plug something in. This lesson connects two servers (one instantly useful, one from your own gap list), runs real tasks through them, and teaches the verification habit that applies to every connection you'll ever add: prove the connection with a read before you trust it with anything more.

What you will learn

  • Add, list, and remove MCP servers in Claude Code.
  • Run the connection check: handshake, menu, read-only proof.
  • Handle credentials the right way on your very first attempt.

Builder principle

First contact with any new connection is always a read. Earn your own trust in it before you let it write.

The mechanics

Claude Code manages servers with the claude mcp command family:

$ claude mcp add [options] <name> -- <command that runs the server>
$ claude mcp list
$ claude mcp remove <name>

Servers can be scoped — available in just this project, or for you everywhere — the same layering as memory, commands, and Skills (you know the filing question by heart now: where is this connection true? The team database server belongs to the project; your personal calendar belongs to you).

Connection one: a browser

Start with Playwright — browser automation published by Microsoft. Before running any MCP command copied from a lesson or registry, verify the publisher, package name, exact command, version policy, requested credentials, and tool list. An MCP server runs code and can expose what its process can reach.

$ claude mcp add playwright -- npx --yes @playwright/mcp@0.0.78

This course pins the reviewed package version instead of executing a moving @latest target. Version 0.0.78 was checked on July 23, 2026; before changing it, review the official package provenance, release notes, and tool surface, then update the pin deliberately.

Start a session and run the three-step connection check — memorize this ritual, it's the same for every server forever:

1. Handshake — is it connected?

/mcp

The /mcp command shows connected servers and their status.

2. Menu — what can it do?

What tools does the playwright server give you? Group them:
which ones READ (look at pages) vs WRITE (click, type, navigate)?

Reading the menu yourself, once, before first use — non-negotiable ritual step, and you already know why from your window-shopping trip.

3. Read-only proof — one harmless task:

Open my live site (https://YOURNAME.github.io/quick-win/) and
describe what you see. Then check it at phone width and tell me
if anything looks off.

Sit with what just happened: your agent looked at your actual deployed site — rendered, styled, live — and reported like a QA tester. The verify phase of your loop just gained eyes. (The rude-test pass from 4.4? It can run itself now. That thought should be connecting to Chapter 7 in your head — hold it, the exercise below.)

Connection two: from your gap list

Now your starred system from 8.1. The pattern for a server needing credentials — say a read-only database connection:

$ claude mcp add --env DB_URL="$DATABASE_URL" --transport stdio mydb -- npx @your/db-server

Claude's options come before the server name; -- separates them from the server command. --env passes the value through the server process environment rather than committing it to source. That prevents one leakage path, not all misuse: the server code can read and use the credential, and model-invoked tools can request actions within its scope. Use a dedicated least-privilege credential, reviewed server code or trusted publisher, test data, and provider-side limits. Never paste secrets into the session or commit them.

Then the same three-step check: handshake, menu, read-only proof. Use a synthetic or dedicated test database first. "Read-only" protects data integrity, not confidentiality or cost: a reader may still expose every row or run an expensive query.

When it doesn't connect (a rite of passage): /mcp shows the status; the usual suspects are a missing env var, a typo'd command, or the server package needing a first-run install. Debug it with the 6.3 method — reproduce (/mcp output is your evidence), hypothesize, check one at a time. Yes, the debugging method works on plumbing too. Everything composes; that's the course's whole thesis.

Making it stick

A connection that works today should work — and be understood — in six months:

  1. Document it in CLAUDE.md: ## Connections — one line per server: what it reaches, what it's for, READ or WRITE posture. Future sessions (and future you) get the map.
  2. Log the decision: docs/decisions.md — why this server, why this scope, what you explicitly did not enable.
  3. Fold it into a Skill — the payoff thought from earlier: your ship-check Skill's process can now include "open the live URL with playwright and run the visual pass at 375px." Packaged expertise, live hands. This is the full stack clicking together.

Two servers connected, checked, documented — you just did "integration work," the thing that used to be a job title. If the credentialed one felt heavy, connect two easy read-only ones instead and bank the ritual; the muscle transfers.

Playwright + your stack's DB server is the starter kit; the high-ROI adds are the ones touching your daily loop — GitHub/GitLab server for PRs and issues, your observability platform, your cloud provider. Then the force-multiplier move: project-scoped server config in the repo (checked in, env vars for secrets) so the whole team's agents get identical hands. Uneven agent tooling across a team is uneven output quality — same argument as shared Skills, same fix.

Try it now

  1. Inspect the current official command, publisher, package/version, and tool list; then connect Playwright and run the full three-step check.
  2. Connect your starred gap-list server (or a second read-only one); three-step check again.
  3. Document both: CLAUDE.md connections section + decision log entries.
  4. The composition exercise: add one tool-using step to an existing Skill (ship-check + playwright is the natural first). Test it fresh-session, 7.3-style.
  5. Journal: what did the agent's verify phase catch through the browser that it couldn't have caught before?

Check your understanding

  • Recite the three-step connection check and what each step proves.
  • How do credentials travel to a server, and name two places they must never appear.
  • Why document connections in CLAUDE.md and decisions.md — what does each capture?
  • What does "everything composes" mean concretely, in this lesson?