Claude Code: the production-ready setup guide

Claude Code is the AI coding assistant that, depending on which survey you read, is somewhere between the #1 and #2 most-used coding agent of 2026. Most setup guides stop at "install the CLI and paste your API key". That gets you to "demo works on my laptop". It does not get you to "I trust this to run against real repos with real tokens for the next six months".

This is the longer version. The version where you set it up once and don't have to think about credentials, multi-account, MCP servers, or CI again. It assumes you've never used Claude Code before and ends with a setup you can actually leave running in your workflow.

Sections:

• What Claude Code actually is
• Install and first-run
• Skills vs MCP servers
• Wiring authentication that doesn't break
• Connecting MCP servers
• Running Claude Code in CI
• Multi-account setups
• What to watch for
• FAQ

What Claude Code actually is

Claude Code is two things at once. It's a CLI tool, claude, that runs on your laptop. And it's a frame for Claude (the model) to act inside, with access to:

• Your filesystem. It can read and write files in the project directory.
• Your shell. It can run subprocesses: git, npm, pytest, whatever you have installed.
• Network. It can fetch URLs, hit APIs, and call other services.
• MCP servers. External tools published over the Model Context Protocol, which we'll cover below.
• Skills. Markdown files that teach Claude how to use the above to do a specific kind of work.

The combination of those is what makes it different from chat. Chat answers questions. Claude Code does work.

For a sense of scale: in a typical session it might read a dozen files, run half a dozen subprocesses, hit two or three APIs, and edit several files. All of that without you babysitting each step. That capability is also what makes the credential and security questions matter.

Install and first-run

Anthropic recommends the native installer for macOS, Linux, and Windows:

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew install anthropic/claude/claude

# Windows
winget install Anthropic.Claude

The npm package @anthropic-ai/claude-code still exists and works, but as of 2026 it's marked deprecated in favor of the native installer. If you're scripting installs across many machines, the curl / Homebrew / WinGet paths are the stable ones.

First run:

claude

It prompts you for an Anthropic API key (paste from console.anthropic.com → API Keys), opens an editor session, and you're in. The basic sanity check is to ask:

What files are in this directory?

If it reads them and lists them, you're configured. If it errors on permissions, you may need to grant filesystem access on macOS via Settings → Privacy & Security.

This is the moment where most tutorials end. We're not done.

Skills vs MCP servers

The two extension mechanisms in Claude Code are skills and MCP servers. They get conflated and they shouldn't.

Skills are markdown files that teach Claude procedural knowledge. A skill is a SKILL.md (with optional supporting files) that describes "when to use me" and "what to do step by step". Claude reads the skill when the trigger condition matches, then executes the procedure. Skills live in ~/.claude/skills/ (user-scoped) or .claude/skills/ (project-scoped).

Examples of useful skills:

• A skill that knows how to draft a PR description from the current diff.
• A skill that handles credential setup via authsome.
• A skill that runs your team's specific linting and test sequence.

MCP servers are external programs that expose tools and resources to Claude over the Model Context Protocol. An MCP server might give Claude access to your GitHub, your Linear, your Postgres database, your Slack, your Figma. Each MCP server has tools (functions Claude can call) and resources (data Claude can read).

The complementary relationship: MCP gives Claude tools to call. Skills teach Claude how to use those tools to accomplish real work. A complete setup has both.

A small skill (10-50 lines) is often more useful than a giant MCP server because it encodes the team-specific judgment about when and how to use the tools, which the tools themselves don't carry.

Wiring authentication that doesn't break

This is where most setups regress over time. Here's how I do it now, and why.

The pattern most tutorials show:

export GITHUB_TOKEN="ghp_..."
export OPENAI_API_KEY="sk-..."
export LINEAR_API_KEY="lin_..."
claude

This works on day one. Six months in, the GitHub PAT is from an account you forgot about, the OpenAI key is for a project that got deleted, and the Linear key is from a workspace your team migrated off of. You also have the same export lines in ~/.zshrc, in .envrc, in a .env file, and possibly in your CI config. Each rotation requires you to update all of them.

A better pattern is to put a credential broker between Claude Code and the providers it calls. The broker handles OAuth refresh, multi-account selection, and per-call substitution. The agent process never holds the real keys.

The setup with authsome:

pip install authsome
authsome init
authsome login github   # browser-based, OAuth + auto-refresh
authsome login linear   # API-key form in browser
authsome login openai   # API-key form in browser

Then launch Claude Code under the broker:

authsome run -- claude

In Claude Code's process, the env vars are placeholders (OPENAI_API_KEY=authsome-proxy-managed). The real values land in outbound HTTPS requests at the proxy boundary. If Claude Code gets prompt-injected into reading os.environ and exfiltrating it, the attacker gets placeholders.

I covered the full walk-through, including the mitmproxy CA cert install and the multi-account flow, in Wiring Claude Code to GitHub, Linear, and Stripe.

The alternative is whatever your team's existing secrets manager is (Doppler, Infisical, 1Password CLI, AWS Secrets Manager). These work for the "fetch on startup" pattern but they don't keep secrets out of the agent process at runtime. For why that matters for Claude Code specifically, see AWS Secrets Manager isn't built for AI agents.

Connecting MCP servers

MCP servers are the third-party-integration layer. Claude Code reads its MCP config from ~/.claude.json (user-scoped) or .mcp.json (project-scoped).

A minimal MCP server entry:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

The official @modelcontextprotocol/server-github exposes tools like create_issue, search_repositories, get_file_contents, etc. Claude can call them like local functions.

Better: use the broker for the GitHub credential too. Replace the env block with a wrapper that injects via authsome:

{
  "mcpServers": {
    "github": {
      "command": "authsome",
      "args": ["run", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Now the MCP server runs under the proxy and the GitHub token doesn't appear anywhere in the config file. Same pattern works for any MCP server that talks to an authenticated API.

The Anthropic team has been pushing toward HTTP transport for MCP servers with OAuth 2.1 / DCR for client registration, which is the right direction for production setups. If you're choosing or building an MCP server today, prefer HTTP + OAuth over stdio + env-var-PAT.

Running Claude Code in CI

Claude Code in CI is a real use case. The pattern people use most:

# .github/workflows/claude-pr-review.yml
name: Claude PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          mode: review
          prompt: "Review this PR for security issues. Comment inline."

The action handles authentication, posts comments back via the GitHub API, and reports back to the workflow.

Three things that bite people:

Credential leakage in CI logs. Default GitHub Actions logging will print env vars that get set during a step. Mask any sensitive values explicitly with ::add-mask:: and prefer GitHub Actions secrets over plaintext env. Better, use OIDC to mint short-lived tokens at job time rather than long-lived PATs in the repo's secrets.

Prompt injection from PR titles and descriptions. The April 2026 GitHub-comment hijack worked against Claude Code's GitHub Action via this exact path. Don't run Claude Code with write access on PRs from untrusted forks unless you've explicitly thought about the prompt-injection surface.

Cost runaway. A misconfigured loop can burn through Anthropic credit fast. Set a max-tokens or max-cost budget per run. The Anthropic console lets you set per-key spending limits; use them.

For CI specifically, "credential brokering" isn't quite the right primitive (CI is unattended; brokers assume a human can occasionally re-auth). The pattern is OIDC + per-job short-lived tokens, or a GitHub App's installation token, with the long-lived secrets stored in your CI provider's secret manager. The broker is for your laptop and your dev boxes; CI has its own model.

Multi-account setups

This is the most common "I wish someone had told me" gotcha for anyone with both a personal and a work GitHub account, or multiple Linear workspaces, or multiple Stripe environments.

The default Claude Code config has one of each credential. If your work is in two GitHub orgs and you want Claude Code to use the right identity per repo, you need a switching mechanism. Options:

Project-scoped .mcp.json. Put the right MCP server config in each project's .mcp.json with a project-specific token. Works but you have plaintext tokens in committed config files unless you carefully gitignore them.

Broker per-connection. Authsome's multiple-connections pattern: authsome login github --connection work, authsome login github --connection personal, then authsome set-default github work to switch which one Claude Code uses for the next run. No tokens in any config file.

Separate Claude Code state directories. Set CLAUDE_HOME (or the equivalent env var your version supports) to a different path per identity, and launch Claude Code with that env set. Heavyweight but airtight. Useful for teams that genuinely need full isolation between work and personal sessions.

For most laptop users, the broker-per-connection pattern is the smoothest. The token never leaves the broker's vault, and switching identities is one command.

What to watch for

A short list of things that have bitten me or people I've talked to:

• The .claude/ directory in committed repos. Settings, prompts, and any cached state live here. Make sure .claude/ (or whichever subset you don't want public) is in your .gitignore. Some teams commit .claude/skills/ intentionally to share skills across the team; that's fine if the skills don't contain anything sensitive.
• The mitmproxy CA cert prompt on first authsome run -- claude. If you skip it, Claude Code's HTTPS calls fail with CERTIFICATE_VERIFY_FAILED. See the cert section in the wiring guide.
• MCP server processes outliving the Claude Code session. Some MCP servers don't clean up cleanly. ps aux | grep mcp is a good thing to run every few days; kill the stragglers.
• Claude Code asking for permission for every shell command. That's the default, and it's mostly correct, but for a long-running session it gets noisy. You can grant broader permission per-session, but understand the threat model. The narrower the permission, the safer.
• Skills loading silently on session start. Skills in ~/.claude/skills/ get loaded by default. A malicious skill placed there by a compromised package could affect every Claude Code session. Treat your ~/.claude/skills/ directory like you'd treat your ~/.bashrc.

FAQ

Is Claude Code free?

The CLI is free. Usage is metered against your Anthropic API key. Anthropic has a console pricing page; budget on the order of $5-50 per heavy month for individual use, much more for production workloads.

Can Claude Code work without an internet connection?

No. Every prompt round-trips to Anthropic's servers. Local-only LLMs (Ollama, llama.cpp) are a different ecosystem; Claude Code specifically requires Anthropic API access.

How does Claude Code compare to Cursor / Codex / OpenCode?

They're different products with overlapping capabilities. Claude Code is CLI-first and runs locally with shell access. Cursor is editor-first (a VS Code fork). Codex (OpenAI) is also CLI-first. OpenCode is open-source and provider-agnostic. The credential pattern (broker between agent and provider) applies the same way to all of them.

What's the difference between a "skill" and a "rule"?

A skill is a procedural file Claude reads when triggered. A rule (in tools like Cursor's .cursorrules or Claude Code's CLAUDE.md) is always-on context, prepended to every prompt. Skills scale; rules can bloat the context window.

Does Claude Code support multiple models?

By default it uses Claude. There's experimental support for some Anthropic-compatible endpoints; check the docs. For production, stick with the official Anthropic API.

Where do skills come from?

Three main sources today: the official anthropic-skills repo, individual project authors who ship a SKILL.md, and your team's own. Authsome ships a skill that teaches Claude Code how to drive the CLI for credential setup, which is the recommended way to integrate.

Can I use Claude Code without putting any credentials on my machine?

Not really. At minimum your Anthropic API key has to live somewhere Claude Code can read it. The broker pattern moves provider credentials (GitHub, Linear, Stripe, etc.) out of the process, but the Anthropic key still has to be accessible to start the session.

Is Claude Code safe to run on production code?

Yes, with the right setup. The right setup is: credential brokering for provider keys, narrower permission grants (don't allow arbitrary shell unless you actually need it), .gitignore discipline for sensitive files, awareness of prompt-injection through PR titles and READMEs. None of these are unique to Claude Code; they apply to any coding agent.

Summary

A production-ready Claude Code setup has four things:

1. The CLI itself, installed and authenticated to Anthropic.
2. A credential broker between the agent and any other provider it calls.
3. MCP servers configured for the third-party services your work touches.
4. Per-project, per-account discipline so multi-identity workflows don't go wrong.

The first one takes a minute. The other three take maybe an afternoon, total. After that, Claude Code stops being a thing you fiddle with weekly and becomes a fixture in your workflow.

The pieces that most people skip on day one are the credential layer (covered in Stop putting API keys in environment variables) and the prompt-injection threat model (covered in How prompt injection becomes credential exfiltration). Those are the same two pieces that show up in every incident postmortem six months later.

Priyansh Khodiyar

Maintainer

Works on authsome and the agentr.dev tooling.