Tag: Developer Reference

  • Claude Skills vs MCP vs Connectors vs Plugins: What Each One Is (2026)

    Claude Skills vs MCP vs Connectors vs Plugins: What Each One Is (2026)

    Last verified: June 13, 2026

    The simplest way to keep these straight: Skills teach Claude how to do a task, MCP servers and Connectors give Claude access to external systems, Plugins bundle several of these together, and Hooks and slash commands control a Claude Code session. A Skill is a folder of instructions Claude reads when relevant. MCP (the Model Context Protocol) is an open standard that connects Claude to your tools and data. A Connector is Anthropic’s packaging of a remote MCP server inside the Claude apps. A Plugin packages any combination of commands, agents, MCP servers, hooks, and skills for Claude Code. Every definition below is taken verbatim from Anthropic’s official documentation, fetched on the verification date.

    The one-glance comparison

    This is the liftable summary. Each row is one mechanism; the third column is the distinction people most often get wrong — whether the thing teaches Claude how to do something or gives Claude access to something.

    Type What it is Teaches-HOW or gives-ACCESS Where it runs How you install / enable it
    Skill A modular capability that packages instructions, metadata, and optional resources (scripts, templates) in a SKILL.md file that Claude uses automatically when relevant. Teaches HOW. Provides domain-specific expertise: workflows, context, and best practices (procedural knowledge). In Claude’s code execution environment / VM, where Claude has filesystem access, bash, and code execution. claude.ai: upload a zip under Settings > Features. API: upload via the Skills API (/v1/skills) with the required beta headers (code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14). Claude Code: a SKILL.md directory under ~/.claude/skills/ or .claude/skills/.
    MCP server An implementation of the Model Context Protocol — “an open-source standard for connecting AI applications to external systems.” Described as “a USB-C port for AI applications.” Gives ACCESS. Connects Claude to data sources, tools, and workflows so it can access information and perform tasks. Local (stdio) servers run as processes on your machine; remote servers run over HTTP (recommended) or SSE (deprecated). In Claude Code: claude mcp add, at local, project, or user scope. Also configurable in .mcp.json or imported from Claude Desktop / claude.ai.
    Connector A feature that “let[s] Claude access your apps and services, retrieve your data, and take actions within connected services.” Custom connectors use remote MCP. Gives ACCESS. Same access role as MCP — a Connector is the in-app packaging of a remote MCP server. Custom connectors are reached from Anthropic’s cloud infrastructure, not from your local machine. In the Claude apps under Customize > Connectors (or the in-chat “+” menu). Add a directory connector, or “Add custom connector” by URL.
    Plugin “A lightweight way to package and share any combination of” Claude Code customizations. Both — it’s a container. Bundles things that teach HOW (commands, skills) and things that give ACCESS (MCP servers), plus hooks and subagents. In Claude Code — “they’ll work across your terminal and VS Code.” The /plugin command (public beta). For a marketplace: /plugin marketplace add user-or-org/repo-name, then install from the /plugin menu.
    Hook “User-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code’s lifecycle.” Controls behavior. Provides deterministic control rather than relying on the LLM to decide. In Claude Code, firing at lifecycle events (e.g. PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop). Configured in JSON settings files such as ~/.claude/settings.json or .claude/settings.json, or bundled in a plugin.
    Slash command A command starting with / that controls a Claude Code session. Includes built-ins (e.g. /help, /compact) and custom commands. Teaches HOW (custom) / controls session (built-in). Custom commands have been merged into Skills. In the Claude Code session (terminal or VS Code). Built-ins ship with Claude Code. Custom: a Markdown file under .claude/commands/ (project) or ~/.claude/commands/ (personal); a .claude/skills/<name>/SKILL.md does the same.

    Skills: teaching Claude a procedure

    An Agent Skill is “a directory containing a SKILL.md file” with YAML frontmatter plus instructions, and optionally additional markdown files, executable scripts, and reference resources. The point is procedural knowledge — it turns “general-purpose agents into specialists” by giving Claude the workflows and best practices for a task, the way you’d write an onboarding guide for a new teammate. Anthropic ships pre-built Skills for PowerPoint, Excel, Word, and PDF, and you can author your own.

    What makes Skills cheap to install in bulk is progressive disclosure: Claude loads information in stages instead of all at once. The numbers below come straight from Anthropic’s Skills overview.

    Loading level When loaded Token cost (per Anthropic docs) Content
    Level 1: Metadata Always, at startup ~100 tokens per Skill name and description from the YAML frontmatter
    Level 2: Instructions When the Skill is triggered Under 5k tokens The SKILL.md body — workflows and guidance
    Level 3+: Resources As needed Effectively unlimited Bundled files read or executed via bash without loading their contents into context

    The name field is capped at 64 characters (lowercase letters, numbers, hyphens; it cannot contain the reserved words “anthropic” or “claude”), and the description is capped at 1,024 characters. One important constraint: custom Skills do not sync across surfaces — a Skill uploaded to claude.ai is not automatically available via the API, and Claude Code Skills are filesystem-based and separate from both.

    MCP: the open standard for access

    The Model Context Protocol is, in Anthropic’s words, “an open-source standard for connecting AI applications to external systems.” The canonical analogy: “Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.” Using MCP, “AI applications like Claude or ChatGPT can connect to data sources (e.g. local files, databases), tools (e.g. search engines, calculators) and workflows (e.g. specialized prompts).”

    An MCP server can expose three kinds of building block — tools, resources, and prompts. In Claude Code, resources are referenced with @server:protocol://resource/path and prompts surface as commands in the form /mcp__servername__promptname. You connect a server with claude mcp add, choosing a transport and a scope:

    Scope Loads in Shared with team Stored in
    Local (default) Current project only No ~/.claude.json
    Project Current project only Yes, via version control .mcp.json in project root
    User All your projects No ~/.claude.json

    For transports, HTTP is “the recommended option for connecting to remote MCP servers,” local stdio servers “run as local processes on your machine,” and SSE is explicitly marked deprecated in favor of HTTP.

    Connectors: MCP, packaged for the apps

    A Connector is how the Claude apps surface MCP. Per Anthropic’s help center, “Connectors let Claude access your apps and services, retrieve your data, and take actions within connected services,” and “Custom connectors using remote MCP are available on Claude, Cowork, and Claude Desktop.” So a Connector is not a different technology from MCP — a custom connector is a remote MCP server wired into the Claude UI.

    The most consequential detail is where the connection originates: “Custom connectors (remote MCP servers) are reached from Anthropic’s cloud infrastructure, not from your local machine.” That means a custom-connector MCP server must be reachable over the public internet — one hosted only on a private network, behind a VPN, or blocked by a firewall will not connect even if you can reach it yourself.

    Aspect Directory (pre-built) connector Custom connector
    Source Pre-built integrations in the Connectors Directory Added by you via a remote MCP server URL
    Plan availability Available across Claude plans Free, Pro, Max, Team, and Enterprise
    Free-plan limit Per directory “Free users are limited to one custom connector.”
    Where to add it Customize > Connectors, or the in-chat “+” > Connectors > Manage connectors

    Plugins: a bundle, not a single thing

    A Plugin is “a lightweight way to package and share any combination of” Claude Code customizations. The official announcement lists four bundle components, and the Claude Code documentation adds skills as a fifth thing a plugin can carry:

    Component What it adds
    Slash commands Custom shortcuts for frequently-used operations
    Subagents Purpose-built agents for specialized development tasks
    MCP servers Connections to tools and data sources through MCP
    Hooks Customizations of Claude Code’s behavior at key workflow points
    Skills Per the Claude Code docs, a plugin can include a skills/ directory; plugin skills use a plugin-name:skill-name namespace

    You install a plugin “directly within Claude Code using the /plugin command.” To pull from a marketplace — “curated collections where other developers can discover and install plugins” — you run /plugin marketplace add user-or-org/repo-name and then install from the /plugin menu. Plugins “work across your terminal and VS Code.” Plugins were announced on October 9, 2025, as a public beta for all Claude Code users.

    Hooks and slash commands: controlling the session

    The last two mechanisms aren’t about adding capability — they’re about controlling a Claude Code session. Hooks are “user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code’s lifecycle.” Their defining property is determinism: they provide deterministic control rather than relying on the LLM to make decisions. A PreToolUse hook can, for example, block a destructive rm -rf command regardless of what Claude intended. Hooks are configured in JSON settings files (such as ~/.claude/settings.json or a project’s .claude/settings.json) and fire at events including SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop.

    Slash commands start with / and control the session. Built-in commands like /help and /compact ship with Claude Code. Custom commands are Markdown files — a project command lives at .claude/commands/<name>.md and a personal one at ~/.claude/commands/<name>.md, with the file name becoming the command. As of the 2026 Claude Code docs, custom commands have been merged into Skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md “both create /deploy and work the same way,” and existing .claude/commands/ files keep working.

    Is a Connector the same as an MCP server?

    Effectively yes, for custom connectors. Anthropic states “Custom connectors using remote MCP are available on Claude, Cowork, and Claude Desktop,” and that they “are reached from Anthropic’s cloud infrastructure.” A Connector is the Claude-app packaging of a remote MCP server; MCP is the underlying open standard.

    What’s the difference between a Skill and an MCP server?

    A Skill teaches Claude how to do a task — it “provide[s] Claude with domain-specific expertise: workflows, context, and best practices.” An MCP server gives Claude access to external systems — it connects Claude “to data sources, tools and workflows.” One is procedural knowledge; the other is a connection.

    Do Skills cost a lot of context tokens?

    Not until used. Per Anthropic’s docs, Level 1 metadata costs about 100 tokens per Skill and is always loaded; the full SKILL.md body (under 5k tokens) only loads when the Skill is triggered; and bundled resources are read on demand with effectively no upfront cost. This is the “progressive disclosure” design.

    What can a Claude Code plugin contain?

    “Any combination of” slash commands, subagents, MCP servers, and hooks, per the announcement; the Claude Code documentation adds that a plugin can also bundle a skills/ directory. You install one with the /plugin command, optionally from a marketplace added via /plugin marketplace add.

    Are custom slash commands still a thing?

    They still work, but they’ve been folded into Skills. The Claude Code docs state custom commands “have been merged into skills,” that existing .claude/commands/ files keep working, and that a command file and an equivalent SKILL.md both produce the same / command. Skills add optional extras like supporting files and automatic invocation.


  • Migrating Off Retired Claude Models: The Breaking-Change Checklist (2026)

    Migrating Off Retired Claude Models: The Breaking-Change Checklist (2026)

    Last verified: June 13, 2026

    Claude Opus 4 (claude-opus-4-20250514) and Claude Sonnet 4 (claude-sonnet-4-20250514) are deprecated and retire on June 15, 2026, after which requests to them return a 404. The official replacements are claude-opus-4-8 and claude-sonnet-4-6. But swapping the model string alone will break a working integration: depending on which target you choose, several request parameters that were valid on the May 2025 models now return a 400 error, and two changes alter behavior silently. This page maps each removed or changed parameter to the exact failure and the fix.

    One distinction governs the whole migration. The Opus path (to claude-opus-4-8) is the strict one: it removes temperature/top_p/top_k and manual thinking budgets entirely. The Sonnet path (to claude-sonnet-4-6) is gentler: it keeps sampling parameters (with the older “one of temperature or top_p, not both” rule) and still accepts budget_tokens as deprecated-but-functional. The one rule both paths share: assistant-turn prefills now return 400.

    The breaking-change matrix

    Each row is a change that breaks on at least one migration target. “Error” means the API rejects the request server-side (HTTP 400) even though the SDK request type still type-checks. “Silent” means no error — the behavior simply differs.

    Change On Opus 4.8 On Sonnet 4.6 Symptom Fix
    thinking: {type:"enabled", budget_tokens:N} 400 error (removed) Deprecated, still works 400 on Opus; cost/latency drift on Sonnet thinking: {type:"adaptive"} + output_config.effort
    temperature / top_p / top_k 400 error (removed) Keep only one of temperature or top_p 400 on Opus if any set; 400 on Sonnet if both set Remove on Opus; steer via prompt. Keep one on Sonnet
    Assistant-turn prefill (last message role:"assistant") 400 error 400 error Request rejected on both output_config.format (structured outputs) or system-prompt instruction
    thinking.display default Defaults to "omitted" Returns summarized text Reasoning text empty on Opus (silent) Set display: "summarized" on Opus
    Tokenizer New tokenizer (more tokens) Unchanged tokenizer Same text counts higher on Opus; max_tokens too tight Re-baseline with count_tokens; add headroom
    output_format (top-level) Deprecated API-wide Deprecated API-wide Works, but slated for removal Move to output_config: {format: {...}}

    Model ID swaps and retirement dates

    Retiring model Model ID Retires Replacement
    Claude Opus 4 claude-opus-4-20250514 (alias claude-opus-4-0) June 15, 2026 claude-opus-4-8
    Claude Sonnet 4 claude-sonnet-4-20250514 (alias claude-sonnet-4-0) June 15, 2026 claude-sonnet-4-6

    These are the original May 2025 models, not the later Opus 4.6 or Sonnet 4.5 releases. Use the exact replacement strings above — do not append a date suffix to claude-opus-4-8 or claude-sonnet-4-6 (they are dateless pinned snapshots).

    budget_tokens to adaptive thinking

    The Opus path removes the fixed thinking budget. thinking: {type:"enabled", budget_tokens:N} returns a 400 on claude-opus-4-8. The replacement is adaptive thinking — the model decides how much to think per request — with overall depth controlled by the effort parameter (low | medium | high | xhigh | max). There is no direct token-count equivalent; effort is an output-level control, not a thinking budget.

    # Before (Claude Opus 4 / Sonnet 4)
client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

# After (Claude Opus 4.8)
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

    On the Sonnet path, budget_tokens is deprecated but still functional on claude-sonnet-4-6, so it will not 400 — but you should still migrate to adaptive thinking. Note also that Sonnet 4.6 defaults to effort: "high" where Sonnet 4 had no effort parameter at all; if you do not set it explicitly you may see higher latency and token use after the swap.

    Sampling parameters: removed vs. restricted

    This is where the two paths diverge most. On claude-opus-4-8, setting temperature, top_p, or top_k to any non-default value returns a 400. Remove them entirely and steer behavior through prompting instead. (If you used temperature=0 for determinism, note it never guaranteed identical outputs on prior models either.)

    # Opus path — sampling params 400 on claude-opus-4-8
# Before
client.messages.create(
    model="claude-opus-4-20250514",
    temperature=0.7,
    top_p=0.9,
    messages=[...],
)

# After — remove them
client.messages.create(
    model="claude-opus-4-8",
    messages=[...],
)

    On claude-sonnet-4-6 the older Claude 4.x rule still applies: you may pass one of temperature or top_p, but passing both returns a 400. So a Sonnet 4 to Sonnet 4.6 move only requires dropping one of the two if you were setting both.

    Assistant-turn prefills to structured outputs

    Prefilling the final assistant turn — ending your messages array with a role: "assistant" message to force a response shape — returns a 400 on both claude-opus-4-8 and claude-sonnet-4-6. This is the one breaking change you cannot dodge by choosing the gentler target. The replacement depends on what the prefill was doing.

    Prefill was used for Replacement
    Forcing JSON / YAML / schema output output_config.format with a json_schema
    Forcing a classification label A tool with an enum field, or structured outputs
    Skipping preambles (“Here is…”) System-prompt instruction: respond directly, no preamble
    Continuing an interrupted response Move continuation into the user turn
    Steering around bad refusals Usually unnecessary now — plain user-turn prompting suffices 
    # Before (fails on both targets) — prefill forcing JSON shape
messages=[
    {"role": "user", "content": "Extract the name."},
    {"role": "assistant", "content": "{\"name\": \""},
]

# After — structured outputs replace the prefill
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": SCHEMA}},
    messages=[{"role": "user", "content": "Extract the name."}],
)

    Thinking display: the silent one

    On claude-opus-4-8, thinking blocks still stream, but their thinking text field is empty unless you opt in — the default is display: "omitted". There is no error; if your UI rendered the summarized reasoning, it now shows a long pause before output. Restore it by setting the display mode:

    thinking = {
    "type": "adaptive",
    "display": "summarized",  # default is "omitted" on Opus 4.8/4.7
}

    The block-field name is unchanged — it is still block.thinking on a thinking-type block. The fix is the request parameter, not the response-handling code. (Sonnet 4.6 is not affected by this default change.)

    The new tokenizer: re-baseline max_tokens

    This change is Opus-only and easy to miss because it produces no error. claude-opus-4-8 uses the tokenizer introduced with Opus 4.7, under which the same text tokenizes to roughly 1x–1.35x as many tokens — up to about 35% more, around 30% on typical content, varying by workload. Three consequences:

    What to check Why
    max_tokens ceilings and compaction triggers The same output now consumes more tokens; tight limits truncate mid-thought
    Client-side token estimators (e.g. fixed char-to-token ratios) Calibrated against the old tokenizer; now undercount
    Cost and rate-limit dashboards count_tokens returns higher numbers; re-baseline before reacting

    Re-run client.messages.count_tokens(model="claude-opus-4-8", ...) on a representative sample of your prompts. Do not apply a blanket multiplier. Sonnet 4.6 keeps the older tokenizer, so a Sonnet 4 to Sonnet 4.6 move has no tokenizer re-baseline to do.

    The full checklist

    Step Opus 4 to 4.8 Sonnet 4 to 4.6
    Update model ID string Required Required
    Replace budget_tokens with adaptive thinking Required (400) Recommended (deprecated)
    Sampling params Remove all (400) Keep only one (both 400)
    Remove assistant-turn prefills Required (400) Required (400)
    Set display: "summarized" if showing reasoning Required for visible thinking Not applicable
    Re-baseline max_tokens for new tokenizer Required Not applicable
    Set effort explicitly Defaults to high Defaults to high
    Move output_format to output_config.format Recommended Recommended
    Verify tool inputs parsed with a JSON parser Recommended Recommended
    Spot-check one request, then roll out Required Required

    If you run Claude Code, /claude-api migrate applies the model swap, breaking-parameter changes, prefill replacement, and effort calibration across a codebase, then produces a verify-it-yourself checklist. It asks you to confirm scope before editing any files.

    Is migrating off Claude Opus 4 really not just a model-string change?

    No. Moving to claude-opus-4-8 also requires removing temperature/top_p/top_k and any budget_tokens (all now return 400), removing assistant-turn prefills (400), opting back into summarized thinking if your UI shows it, and re-baselining max_tokens for the new tokenizer. Only the Sonnet 4 to Sonnet 4.6 move is close to a drop-in — and even that requires removing prefills.

    When exactly do Claude Opus 4 and Sonnet 4 stop working?

    June 15, 2026. After that date, requests to claude-opus-4-20250514 and claude-sonnet-4-20250514 return a 404. These are the original May 2025 models, not Opus 4.6 or Sonnet 4.5.

    What replaces budget_tokens now that it errors on Opus?

    Adaptive thinking (thinking: {type:"adaptive"}) plus the effort parameter inside output_config. There is no exact token-count equivalent: the model decides how much to think per request, and effort (low through max) tunes overall depth and spend. On Sonnet 4.6, budget_tokens still works but is deprecated.

    Why does the same prompt cost more tokens on Opus 4.8?

    Opus 4.8 uses the tokenizer introduced with Opus 4.7, under which the same text produces roughly 1x–1.35x as many tokens (about 30% more on typical content, up to ~35%). Re-run the count_tokens endpoint against claude-opus-4-8 and give max_tokens and compaction triggers extra headroom. Sonnet 4.6 keeps the older tokenizer, so it is unaffected.

    My thinking summaries disappeared after migrating to Opus — is that a bug?

    No. On Opus 4.8 (and 4.7), thinking.display defaults to "omitted", so thinking blocks stream with an empty text field. Set display: "summarized" in your thinking config to restore visible reasoning. The field name is unchanged; only the default flipped.


  • Claude Code Billing in 2026: Subscription Usage vs the Agent Credit Pool

    Claude Code Billing in 2026: Subscription Usage vs the Agent Credit Pool

    Last verified: June 13, 2026

    Claude Code has two billing models, and which one applies depends on how you run it, not just which plan you hold. When you use Claude Code interactively in the terminal or IDE on a Pro or Max plan, it draws from the same subscription usage limits as your Claude.ai chats. But starting June 15, 2026, Anthropic separates out programmatic usage: the Claude Agent SDK, the claude -p headless command, the Claude Code GitHub Actions integration, and third-party apps that authenticate through the Agent SDK will no longer count against your interactive subscription pool. Instead they draw from a new, separate monthly Agent SDK credit, billed at standard API rates. This page documents both models, the exact credit amounts per plan, and the SDK package rename you may also need to handle.

    The two billing models at a glance

    The dividing line is interactive vs. programmatic. One number to remember: setting an ANTHROPIC_API_KEY environment variable overrides your subscription entirely — Claude Code then authenticates with that key and bills as pay-as-you-go API usage, regardless of plan.

    Usage type How it runs Billed against
    Interactive Claude Code Terminal or IDE, human at the keyboard Pro/Max subscription usage limits
    Claude.ai chat Web, desktop, mobile Pro/Max subscription usage limits
    Agent SDK (Python/TypeScript) Your own programmatic projects Separate Agent SDK credit (from June 15, 2026)
    claude -p (non-interactive) Headless / scripted Claude Code Separate Agent SDK credit (from June 15, 2026)
    Claude Code GitHub Actions CI/CD automation Separate Agent SDK credit (from June 15, 2026)
    Any usage with ANTHROPIC_API_KEY set API-key auth instead of subscription Standard API rates (pay-as-you-go)

    What changes on June 15, 2026

    Per Anthropic’s support documentation: “Starting June 15, 2026, Claude Agent SDK and claude -p usage no longer counts toward your Claude plan’s usage limits.” Each subscription tier instead receives a fixed monthly Agent SDK credit. When that credit runs out, additional Agent SDK usage flows to usage credits at standard API rates — but only if you have enabled usage credits. If you have not, “Agent SDK requests stop until your credit refreshes.” Unused credits do not roll over to the next billing cycle, and there is no automatic fallback to the interactive pool.

    Plan Monthly Agent SDK credit
    Pro $20
    Max 5x $100
    Max 20x $200
    Team (Standard seats) $20
    Team (Premium seats) $100
    Enterprise (seat-based Premium) $200

    What stays on the interactive subscription pool, unchanged: Claude conversations on web, desktop, and mobile; and interactive Claude Code in the terminal or IDE. The change is scoped strictly to programmatic execution.

    How each pool is metered and priced

    Claude Code “charges by API token consumption” — the underlying meter is input/output tokens, including thinking tokens billed as output. On a subscription, that token consumption is what counts against your plan limits (interactive) or your Agent SDK credit (programmatic). The Agent SDK credit and any overflow are billed at standard API list rates; the per-model API token prices below are the verified current rates.

    Pool Meter Price basis
    Interactive (Pro/Max) Tokens, against plan usage limits Included in subscription
    Agent SDK credit Tokens, against monthly credit Standard API rates
    Overflow past the credit Tokens, usage credits Standard API rates (only if usage credits enabled)
    API key (ANTHROPIC_API_KEY) Tokens, pay-as-you-go Standard API rates

    Verified current API token prices (per million tokens) for models commonly used in Claude Code:

    Model Model ID Input $/Mtok Output $/Mtok
    Claude Opus 4.8 claude-opus-4-8 $5.00 $25.00
    Claude Sonnet 4.6 claude-sonnet-4-6 $3.00 $15.00
    Claude Haiku 4.5 claude-haiku-4-5 $1.00 $5.00

    Subscription plan prices

    These are the published Claude plan prices the Agent SDK credits attach to. The Max 5x plan starts at $100/month; the $200 figure for Max 20x is documented as the matching Agent SDK credit amount for that tier.

    Plan Price
    Free $0
    Pro $20/month, or $17/month billed annually ($200 up front)
    Max 5x From $100/month
    Team (Standard seat) $25/seat/month, or $20/seat/month billed annually

    The SDK rename: claude-code-sdk to claude-agent-sdk

    Separate from billing, the SDK itself was renamed. Anthropic’s migration guide states: “The Claude Code SDK has been renamed to the Claude Agent SDK.” If you have code on the old package, you must update the package name, imports, and one Python type. The headless CLI command name is unchanged — it is still claude -p.

    Aspect Old New
    npm package (TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
    Python package claude-code-sdk claude-agent-sdk
    Python options type ClaudeCodeOptions ClaudeAgentOptions
    Default system prompt Claude Code’s preset Minimal (opt back in via preset: "claude_code") 
    # TypeScript
npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

# Python
pip uninstall claude-code-sdk
pip install claude-agent-sdk

    Decision: which billing path applies to your work

    If you are… Billing path
    A developer coding interactively in the terminal Subscription usage limits (unchanged)
    Running claude -p in a script or cron job Agent SDK credit (from June 15, 2026)
    Running Claude Code in GitHub Actions Agent SDK credit (from June 15, 2026)
    Building an app on the Agent SDK with subscription auth Agent SDK credit (from June 15, 2026)
    A team or service account wanting budgets + usage reports Set ANTHROPIC_API_KEY → standard API billing

    Does interactive Claude Code billing change on June 15, 2026?

    No. Anthropic’s documentation confirms interactive Claude Code in the terminal or IDE, and Claude conversations on web, desktop, and mobile, continue using subscription usage limits as before. Only programmatic usage — the Agent SDK, claude -p, GitHub Actions, and third-party Agent SDK apps — moves to the separate Agent SDK credit.

    How much is the separate Agent SDK credit?

    $20/month on Pro, $100 on Max 5x, $200 on Max 20x, $20 on Team Standard seats, $100 on Team Premium seats, and $200 on Enterprise seat-based Premium. The credit is billed at standard API rates, does not roll over, and refreshes monthly.

    What happens when the Agent SDK credit runs out?

    Additional Agent SDK usage flows to usage credits at standard API rates — but only if you have enabled usage credits. If you have not enabled them, Agent SDK requests stop until your credit refreshes. There is no automatic fallback to your interactive subscription pool.

    How do I avoid the credit pool entirely?

    Set an ANTHROPIC_API_KEY environment variable. Claude Code and the Agent SDK then authenticate with that key and bill as standard pay-as-you-go API usage, separate from any subscription. This is Anthropic’s recommended path for apps, CI jobs, service accounts, and team-owned projects that need budgets and usage reporting.

    Was the Claude Code SDK renamed?

    Yes. It is now the Claude Agent SDK. The npm package @anthropic-ai/claude-code became @anthropic-ai/claude-agent-sdk, the Python package claude-code-sdk became claude-agent-sdk, and the Python type ClaudeCodeOptions became ClaudeAgentOptions. The claude -p CLI command name is unchanged.


  • Latest Claude Models — June 2026 (Current Lineup, Pricing, and Specs)

    Latest Claude Models — June 2026 (Current Lineup, Pricing, and Specs)

    Updated June 12, 2026. Fable 5 is the current top-tier model, released June 9, 2026. The full lineup: Fable 5 → Opus 4.8 → Sonnet 5 → Haiku 4.5. Pricing and availability verified against Anthropic’s official docs.

    Current Claude Models — Quick Reference

    Model API ID Input $/MTok Output $/MTok Context Best For
    Claude Fable 5 🆕 claude-fable-5 $10.00 $50.00 1M tokens Complex engineering, long-horizon agentic work
    Claude Opus 4.8 claude-opus-4-8 $5.00 $25.00 1M tokens Everyday advanced work, high-volume pipelines
    Claude Sonnet 5 claude-sonnet-5 $3.00 $15.00 1M tokens Balanced capability and speed
    Claude Haiku 4.5 claude-haiku-4-5-20251001 $1.00 $5.00 200K tokens High-speed, cost-sensitive tasks

    All four models support vision, tool use/function calling, and batch processing. Fable 5 and Opus 4.8 are available on AWS Bedrock, Google Cloud Vertex AI, and Microsoft Azure AI Foundry in addition to the direct Anthropic API.

    Claude Fable 5 (June 9, 2026)

    Fable 5 is Anthropic’s first publicly available Mythos-class model — a capability tier previously restricted to research and select enterprise partners. It’s the most capable model Anthropic has released to date.

    What makes Fable 5 different:

    • SWE-bench Verified: 95.0% (vs 88.6% for Opus 4.8)
    • SWE-bench Pro: 80.0% (vs 69.2%)
    • Senior Engineer benchmark: 91/100 (vs ~63/100)
    • Adaptive extended thinking (always on, not a mode switch)

    Important limitations:

    • 2x the cost of Opus 4.8 ($10/$50 vs $5/$25)
    • Mandatory 30-day data retention — not available under zero data retention (ZDR)
    • Safety classifiers route cybersecurity, biology, chemistry, and distillation prompts to an Opus 4.8 fallback — you pay Fable 5 rates for Opus 4.8 output in those domains
    • Higher latency on complex tasks (60 seconds to several minutes vs 3–15 seconds for Opus 4.8)

    Free through June 22, 2026: Claude Pro, Max 5x, Max 20x, Team, and Enterprise subscription plans include Fable 5 at no extra charge during the launch window.

    Claude Opus 4.8

    Opus 4.8 is Anthropic’s current workhorse for serious work — the right default for most API applications and Claude Code use. It supports zero data retention (ZDR), which Fable 5 does not.

    Key specs:

    • Context: 1M tokens
    • Max output: 32K tokens per request
    • Extended thinking: Available (opt-in mode)
    • ZDR: Yes
    • Batch API: Yes (50% discount on batch processing)

    Use Opus 4.8 as your default model unless you have a specific reason to go up to Fable 5 or down to Sonnet/Haiku. It hits the best balance of capability, speed, cost, and data policy flexibility.

    Claude Sonnet 5

    Sonnet 5 targets use cases where response speed matters and you don’t need Opus-level reasoning. It’s the model Anthropic’s own infrastructure runs Claude.ai on for Pro subscribers doing day-to-day chat work.

    Key specs:

    • Context: 1M tokens
    • Max output: 64K tokens per request
    • Extended thinking: Available
    • ZDR: Yes
    • Typical latency: 1–5 seconds for most tasks

    Good for: content generation pipelines, customer-facing chat, document analysis at volume, anything where sub-5-second response time matters.

    Claude Haiku 4.5

    Haiku 4.5 is Anthropic’s fastest and cheapest model. At $1 input / $5 output per million tokens, it’s 10x cheaper than Fable 5.

    Key specs:

    • Context: 200K tokens (smaller than the Opus/Sonnet/Fable 1M window)
    • Max output: 16K tokens per request
    • Latency: Sub-second for most tasks
    • ZDR: Yes

    The 200K context window is the main limitation. For tasks that fit within that window — classification, short-form generation, routing, extraction — Haiku 4.5 is the cost-optimal choice. For longer documents or conversations, step up to Sonnet or Opus.

    How to Choose the Right Claude Model

    The decision framework I use:

    1. Does the task require multi-step reasoning, complex coding, or long-horizon autonomy? → Fable 5 (if cost and latency are acceptable) or Opus 4.8
    2. Is this a routine task at reasonable volume? → Opus 4.8 as the default
    3. Does latency matter more than maximum reasoning depth? → Sonnet 5
    4. Is this high-volume, short-context, cost-sensitive work? → Haiku 4.5
    5. Does your use case require zero data retention? → Any model except Fable 5

    Most production applications use a routing strategy: Fable 5 or Opus 4.8 for the hard jobs, Haiku 4.5 for classification and pre-processing, Sonnet 5 for user-facing response generation.

    Claude Subscription Plans and Model Access (June 2026)

    Plan Price Models Included
    Free $0 Limited Sonnet 5 access
    Pro $20/mo ($17 annual) Sonnet 5, Opus 4.8, Fable 5 (through June 22)
    Max 5x $100/mo All models, 5x usage vs Pro
    Max 20x $200/mo All models, 20x usage vs Pro
    Team Standard $20/seat/mo (annual), $25 month-to-month All models + admin features
    Team Premium $100/seat/mo (annual), $125 month-to-month All models + priority + advanced admin
    Enterprise $20/seat + usage at API rates (contact sales) All models + ZDR + custom retention + SSO

    Claude Code (the CLI tool) is included in all paid subscription plans. API access for building your own applications is separate — billed per token via the Anthropic Console regardless of subscription status.

    Legacy Models (Still Available, No Longer Latest)

    These models are still available via the API but are not Anthropic’s current recommended versions:

    • Claude Opus 4.7 (claude-opus-4-7) — prior Opus tier, succeeded by 4.8
    • Claude Opus 4.6 (claude-opus-4-6) — two generations back
    • Claude Sonnet 4.5 (claude-sonnet-4-5) — prior Sonnet tier
    • Claude 3.5 Haiku / Sonnet / Opus — Claude 3.x generation, still functional for legacy integrations

    If you’re building a new application, start with the current lineup. Legacy model IDs are useful for maintaining compatibility in existing applications that haven’t been updated.

    Platform Availability

    Platform Fable 5 Opus 4.8 Sonnet 5 Haiku 4.5
    Anthropic API (direct) ✓ ✓ ✓ ✓
    AWS Bedrock ✓ ✓ ✓ ✓
    Google Cloud Vertex AI ✓ ✓ ✓ ✓
    Microsoft Azure AI Foundry ✓ ✓ ✓ ✓
    GitHub Copilot ✓ (via Foundry) ✓ ✓ —

    Frequently Asked Questions

    What is the newest Claude model?
    As of June 2026, Claude Fable 5 is the newest and most capable model Anthropic has released. It launched June 9, 2026. The API model ID is claude-fable-5.

    Is Claude Fable 5 the same as Claude 5?
    No. Anthropic changed the naming convention — there is no “Claude 5.” The Fable series is a new tier above the Opus/Sonnet/Haiku hierarchy. Fable 5 is Anthropic’s first Mythos-class model released for general availability.

    What is the most powerful Claude model?
    Claude Fable 5 is currently the most powerful. For tasks where Fable 5’s safety classifier routing applies (cybersecurity, biology, chemistry, distillation), or where zero data retention is required, Claude Opus 4.8 is the appropriate top-tier choice.

    What Claude model does Claude.ai use by default?
    Depends on your plan. Free tier uses a limited version of Sonnet. Pro and Max subscribers access Opus 4.8 as the default with Fable 5 available (through June 22, 2026 included, after that plan-dependent). Claude.ai routes to the appropriate model for your plan automatically.

    How do I use the latest Claude model in the API?
    Set the model parameter in your API request to the model ID. For Fable 5: "model": "claude-fable-5". For Opus 4.8: "model": "claude-opus-4-8". See the full API reference at console.anthropic.com.

    What’s the difference between Claude Opus 4.8 and Fable 5?
    Fable 5 is significantly stronger on complex engineering tasks — SWE-bench Pro: 80% vs 69.2%, and Senior Engineer benchmark: 91 vs ~63 out of 100. The trade-off: Fable 5 costs 2x more ($10/$50 vs $5/$25 per MTok), has higher latency, and requires 30-day data retention. For most work, Opus 4.8 is the right choice. Full Fable 5 vs Opus 4.8 breakdown here.

    Changelog

    • June 12, 2026 — Added Claude Fable 5 (released June 9). Updated pricing table. Added platform availability table.
    • May 2026 — Claude Opus 4.8 and Sonnet 4.6 were the current top-tier models.

    This page is updated as Anthropic releases new models. Last verified: June 12, 2026. For API pricing, check console.anthropic.com — the canonical source.

  • Claude Code Getting Started: Installation, First Run, and the 5 Commands You’ll Use Daily

    Claude Code Getting Started: Installation, First Run, and the 5 Commands You’ll Use Daily

    Claude Code is Anthropic’s official CLI for Claude — a terminal-based agent you can point at any codebase and have it read, write, test, and ship code. It’s different from the Claude.ai chat interface in one key way: Claude Code can act, not just answer. It reads your actual files, runs your actual commands, and makes changes that stick.

    This guide walks you through installation, first run, and the commands that cover 90% of what you’ll do daily.

    What Claude Code Is (and Isn’t)

    Claude Code runs in your terminal. It gives Claude access to your local machine — file system, shell, and any MCP servers you configure — so it can do real engineering work: implement features, fix bugs, write tests, explain unfamiliar codebases, and run multi-step agentic workflows.

    It is not a code autocomplete plugin (that’s what GitHub Copilot does). Claude Code is a conversational agent that works at the task level, not the token level. You describe what you want; it figures out the steps and executes them.

    Installation

    Claude Code requires Node.js 18 or later. Install via npm:

    npm install -g @anthropic-ai/claude-code

    Verify the install:

    claude --version

    That’s the only dependency. Claude Code is a Node.js CLI — no Docker, no Python env, no platform-specific setup beyond Node.

    First-Run Authentication

    The first time you run claude, it walks you through authentication. You have two options:

    Option 1: Claude subscription (Pro, Max, Team, Enterprise)
    Run claude, select “Login with Claude.ai,” and it opens a browser window to authorize. Your subscription covers Claude Code usage — no separate API billing.

    Option 2: Anthropic API key
    Set your API key as an environment variable before running:

    export ANTHROPIC_API_KEY="sk-ant-..."
claude

    Or on Windows:

    $env:ANTHROPIC_API_KEY = "sk-ant-..."
claude

    API key usage is billed per token at standard API rates. For heavy daily use, a Max subscription ($100–$200/month) is usually more economical than API billing.

    Your First Session

    Navigate to a project directory and start Claude Code:

    cd ~/projects/my-app
claude

    Claude Code reads your directory automatically. At the > prompt, describe what you want:

    > What does this codebase do? Give me a 3-paragraph overview.

    Claude reads the files it needs and responds. No configuration required for basic usage — Claude Code infers context from the directory you’re in.

    The 5 Commands You’ll Use Daily

    1. claude — Start an interactive session

    claude

    Launches the REPL (read-eval-print loop). This is where you spend most of your time. Claude has access to your current directory’s files, can run bash commands, and can call any MCP servers you’ve configured.

    Within a session, you can:

    • Ask questions about the codebase
    • Request implementations (“add a rate limiter to the auth middleware”)
    • Have Claude run tests and fix failures
    • Use /help to see available slash commands
    • Use /clear to reset context without leaving the session
    • Press Escape twice to interrupt a running task

    2. claude -p "prompt" — One-shot non-interactive mode

    claude -p "What are all the API endpoints in this codebase?"

    Runs a single prompt and exits. No REPL. Good for scripting, CI pipelines, or quick one-off queries you don’t want to interrupt a workflow for. Output goes to stdout — pipe it wherever you need it.

    claude -p "Summarize the changes in the last 10 commits" | pbcopy

    3. claude mcp add — Connect an external tool

    claude mcp add github -- npx -y @modelcontextprotocol/server-github

    Adds an MCP server to your Claude Code configuration. After running this, Claude can call the server’s tools in any session. Common additions:

    # File system access (scoped to a directory)
claude mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# GitHub integration
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Web search
claude mcp add search -- npx -y @modelcontextprotocol/server-brave-search

    The GitHub and Brave Search servers need API tokens — set them as environment variables before the server starts, or pass them via the --env flag in the mcp add command.

    4. claude -c — Continue the last conversation

    claude -c

    Resumes your most recent Claude Code conversation, including all prior context. Essential for multi-session work on a feature. If you closed the terminal mid-task, claude -c picks up exactly where you left off.

    For a specific prior conversation:

    claude --resume SESSION_ID

    5. claude --model — Select the model for a session

    claude --model claude-opus-4-8

    Claude Code defaults to the most capable available model for your plan. You can override this per session. Current options:

    • claude-fable-5 — Highest capability, complex tasks (2x cost vs Opus 4.8)
    • claude-opus-4-8 — Default for most work, strong balance of quality and speed
    • claude-sonnet-4-6 — Faster responses, good for routine tasks
    • claude-haiku-4-5-20251001 — Fastest, lowest cost, short tasks

    Slash Commands Inside a Session

    While in a Claude Code session (> prompt), these slash commands are available:

    Command What It Does
    /help Show all available commands
    /clear Clear conversation context (keep the session open)
    /compact Compress prior context to save tokens while preserving essential memory
    /cost Show token usage and estimated cost for the current session
    /model Switch the model mid-session
    /review Request a multi-agent code review of the current branch
    /init Generate a CLAUDE.md file with project context for this repo
    /exit End the session

    CLAUDE.md — Project-Level Context

    Drop a CLAUDE.md file in your project root and Claude Code reads it automatically at session start. Use it to encode project-specific context Claude shouldn’t have to re-derive every session:

    # My Project

## Architecture
- Backend: FastAPI + PostgreSQL
- Frontend: React + TypeScript
- Deployed to: AWS ECS

## Development
- Tests: `pytest tests/`
- Local server: `./scripts/start-dev.sh`
- Database migrations: `alembic upgrade head`

## Rules
- Never modify migration files directly
- All API routes go in `src/routes/`
- Use `httpx` not `requests` for HTTP calls

    Generate a starter CLAUDE.md for an existing project with /init.

    Permission Modes

    Claude Code asks for confirmation before running bash commands, creating files, or making other changes — unless you grant it broader permissions. There are three ways to control this:

    • Default: Claude asks before each tool use that modifies files or runs commands
    • --dangerously-skip-permissions: Skip all confirmations. Use only in isolated environments (Docker containers, CI). Not for everyday use on your primary machine.
    • Session-level allowlist: During a session, you can approve individual tools for the rest of the session by selecting “Allow always” when prompted

    For most work, the default confirmation behavior is the right trade-off — it keeps you in the loop on changes without requiring you to pre-define a permission policy.

    IDE Integration

    Claude Code integrates with VS Code and JetBrains IDEs. Install the extension from each marketplace, then launch Claude Code from inside the IDE. This keeps the terminal panel visible alongside your editor without alt-tabbing between windows.

    The IDE extensions also add shortcuts for common actions like opening Claude Code in the current file’s directory and running one-shot queries against the selected code.

    Frequently Asked Questions

    What’s the difference between Claude Code and Claude.ai?
    Claude.ai is the web chat interface — good for questions, document analysis, and writing. Claude Code is a terminal CLI that can access your local files, run commands, and act autonomously on multi-step tasks. Claude.ai can’t modify files on your machine; Claude Code can.

    Does Claude Code cost extra on top of my Claude subscription?
    No. Claude Pro, Max, Team, and Enterprise subscriptions include Claude Code access. You use the same account. Heavy agentic usage counts toward the plan’s usage limits, but there’s no separate Claude Code fee.

    Can Claude Code access the internet?
    Not by default. Claude Code’s built-in WebFetch tool can fetch content from a specific URL when you provide it. For live web search, add the Brave Search or similar MCP server. Claude can’t browse freely without explicit tool access.

    What does Claude Code do with my code?
    Claude Code sends the file contents and context it needs to the Anthropic API for inference. Standard Anthropic API data policies apply — if you’re using an API key, you can configure zero data retention. If you’re using a subscription, default Anthropic retention policies apply. Review Anthropic’s privacy policy for current details.

    Is Claude Code open source?
    Claude Code itself (the CLI client) is not open source — it’s an Anthropic product. The MCP server ecosystem it connects to includes many open-source servers, and the MCP specification itself is open.

    What version of Node.js do I need?
    Node.js 18 or later. Run node --version to check. The Long-Term Support (LTS) version is always a safe choice.

    Last verified: June 12, 2026. Claude Code is updated frequently — run npm update -g @anthropic-ai/claude-code to stay current.

  • Connect Claude Code to Postgres via MCP: The Right Way (2026)

    Connect Claude Code to Postgres via MCP: The Right Way (2026)

    The most useful thing you can wire into Claude Code isn’t a new model or a clever prompt — it’s your actual database. When Claude Code can read your schema, it stops guessing at table names, column types, and relationships. It starts writing queries that work the first time.

    This is the practical walkthrough for connecting Claude Code to a Postgres database via MCP: the command, the credential setup, the safety pattern, and what the workflow actually looks like once it’s running.

    What the Postgres MCP server does

    The official @modelcontextprotocol/server-postgres package (maintained in the MCP reference implementations repo) gives Claude Code four tools: schema inspection, query execution inside a read-only transaction, table detail lookup, and relationship traversal. The server cannot write data — it’s read-only by design in the reference implementation, though third-party variants like postgres-mcp-pro add configurable write access if you need it.

    For the majority of development workflows — debugging, writing migrations, generating queries — read-only is exactly what you want. Claude Code can see the shape of your data without being able to touch it.

    The fastest path: single command setup

    If you just want it running against a local database:

    claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres "postgresql://USER:PASSWORD@localhost:5432/mydb"

    The -y flag on npx auto-accepts the package install so the command doesn’t hang on first run. Verify with:

    claude mcp list

    You should see postgres with a connected status. That’s it — Claude Code now has schema access in the current project.

    Don’t do this for a production database. The connection string above is hardcoded. It goes into ~/.claude.json as plaintext. Use a dedicated local or staging database during development, and use env vars for anything that matters.

    The right way: env vars and a read-only user

    Two things to do before connecting to any real database:

    1. Create a read-only Postgres user:

    CREATE USER claude_readonly WITH PASSWORD 'your-password-here';
GRANT CONNECT ON DATABASE your_db TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

    This user can see everything in public and do nothing else. If something goes wrong — a rogue tool call, a compromised session — blast radius is zero.

    2. Reference the connection string via env var in .mcp.json:

    {
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

    Set DATABASE_URL in your shell environment or in a .env file (not committed). Add .mcp.json to the repo — everyone on the team gets the same server config — but the actual connection string lives in each developer’s local environment. This is the same pattern you already use for application config. It’s the right pattern here too.

    Add the server at project scope so it’s committed:

    claude mcp add --scope project --transport stdio db -- npx -y @modelcontextprotocol/server-postgres

    Then edit .mcp.json to replace the hardcoded connection string with the ${DATABASE_URL} env var reference shown above.

    What Claude Code can actually do with schema access

    Once the server is connected, the workflow changes significantly. A few real examples:

    Schema exploration: Ask Claude Code “what tables are in this database and how are they related?” and it traverses foreign keys, describes join paths, and builds a mental model of your data layer. No more copy-pasting \dt output.

    Query generation: “Write a query that finds users who signed up in the last 30 days but haven’t completed onboarding” produces accurate SQL because Claude Code knows your actual column names. With a generic prompt and no schema access, you’d get plausible-looking SQL that fails because user_status is actually onboarding_state.

    Migration drafting: “I need to add a last_login_at column to users — show me the migration and check for existing timestamp patterns in the schema.” Claude Code inspects the schema first, matches your existing column naming conventions, and produces a migration that fits your codebase.

    Debugging: “This query is returning the wrong count — here’s the query, check it against the schema.” Claude Code can spot that you’re joining on a nullable column, missing a filter on a soft-delete flag, or aggregating before filtering.

    Neon and cloud Postgres

    If you’re on Neon, there’s a first-party MCP server with additional capabilities: branch management, database creation, and schema migrations via Neon’s branching model. Set it up with:

    npx neonctl mcp add

    This runs OAuth through your browser and configures Claude Code automatically. The Neon MCP server is intended for local development and IDE workflows — not production automation — same caution applies.

    Debugging when it doesn’t connect

    Three commands for when the server shows as disconnected:

    claude mcp list          # check registered servers and status
claude mcp test db       # test a specific server
claude --debug           # tail logs including MCP stderr output

    Most connection failures are either a wrong connection string, a missing env var, or Node version issues with npx. The debug log shows the exact error from the server process — read it before assuming the problem is Claude Code.

    The practical baseline

    Five minutes to set up. The productivity delta on any codebase larger than a few tables is immediate — Claude Code stops making column-name mistakes and starts being genuinely useful for data-layer work. Wire up the read-only user, commit the .mcp.json, and add DATABASE_URL to your team’s .env.example. Done.

    The model doing the work in a typical Claude Code session is claude-sonnet-4-6 (workhorse) — it handles schema-aware query generation well without burning through Opus 4.8 credits on every lookup.

    Related Reading

    Frequently Asked Questions

    How do I connect Claude Code to a Postgres database via MCP?

    Run: claude mcp add postgres — npx -y @modelcontextprotocol/server-postgres “postgresql://USER:PASSWORD@localhost:5432/mydb”. The -y flag auto-accepts the package install so the command doesn’t hang. Then run claude mcp list and confirm postgres shows a connected status. Use a local or staging database for this quick path, not production.

    Is the Postgres MCP server read-only?

    Yes. The official @modelcontextprotocol/server-postgres package is read-only by design — it exposes schema inspection, query execution inside a read-only transaction, table detail lookup, and relationship traversal. It cannot write data. Third-party variants like postgres-mcp-pro add configurable write access if you need it.

    What’s the safe way to connect Claude Code to a production database?

    Create a dedicated read-only Postgres user (GRANT SELECT only), and reference the connection string through an environment variable in .mcp.json using ${DATABASE_URL} rather than hardcoding it. Commit .mcp.json so the team shares the server config, but keep the actual connection string in each developer’s local .env. If a session is ever compromised, the blast radius is zero.

    Why does schema access make Claude Code more accurate?

    With schema access, Claude Code reads your real table names, column types, and relationships, so it writes queries that work the first time instead of guessing. Without it, you get plausible-looking SQL that fails because user_status is actually onboarding_state. It also improves migration drafting and query debugging by matching your existing conventions.

    How do I debug a Postgres MCP server that won’t connect?

    Use three commands: claude mcp list to check registered servers and status, claude mcp test db to test a specific server, and claude –debug to tail logs including MCP stderr. Most failures are a wrong connection string, a missing env var, or a Node version issue with npx — the debug log shows the exact server error.

  • Notion MCP Setup with Claude: Complete Config + the Errors Nobody Documents

    Notion MCP Setup with Claude: Complete Config + the Errors Nobody Documents

    Last verified: June 2026.

    There are two ways to connect Notion to Claude over the Model Context Protocol (MCP), and almost every tutorial only covers one of them. Worse, none of them tell you why the connection succeeds but Claude still says it cannot find any of your pages. This guide covers both paths – the hosted OAuth connector and the self-hosted token route – with the exact config, the scopes that matter, the rate limit you will hit, and the specific error strings that show up when something is wrong. It is written from actually running this, not from reading the docs.

    Which Notion MCP should you use: hosted or self-hosted?

    Short answer: use the hosted MCP at https://mcp.notion.com/mcp for almost everything. It uses OAuth, so you never handle a token, and it respects your existing Notion permissions automatically. Use the self-hosted npm server with an internal integration token only when you need headless, unattended automation (a cron job, a server with no human to click “Allow”), because the hosted server requires an interactive OAuth approval that a background process cannot complete.

    Factor Hosted (mcp.notion.com) Self-hosted (npm + token)
    Auth OAuth (interactive) Internal integration token (ntn_)
    Permissions Inherits your full Notion access Only pages you explicitly share
    Setup time ~2 minutes ~10 minutes
    Headless / cron No (needs a human to approve) Yes
    Best for Claude Desktop, Claude Code, daily use Servers, scripts, multi-user backends

    How do I connect Notion to Claude using the hosted MCP?

    This is the fast path. No token, no npm.

    Claude Desktop / Claude.ai: Open Settings > Connectors, click Add custom connector (or pick Notion if it appears in the directory), and paste the URL https://mcp.notion.com/mcp. A Notion OAuth window opens. Approve it, choose which workspace and which top-level pages the connector may see, and you are done. The scope you pick in that OAuth screen is the whole ballgame – see the gotcha below.

    Claude Code (CLI): one command.

    claude mcp add --transport http notion https://mcp.notion.com/mcp

    Then run /mcp inside Claude Code to trigger the OAuth login. After approving, verify it is live:

    claude mcp list

    You should see notion with a connected status. If it shows failed or needs auth, run /mcp again and complete the browser flow – the CLI cannot proceed past OAuth on its own.

    How do I set up the self-hosted Notion MCP with an integration token?

    Use this when you need automation that runs without a human. Three steps: create the integration, get the token, then wire it into your MCP config.

    1. Create the integration and copy the token

    1. Go to https://www.notion.so/my-integrations and click New integration. You must be a Workspace Owner – if the button is greyed out, that is why.
    2. Name it, select the workspace, and choose Internal integration type.
    3. On the integration’s settings page, set Capabilities: Read content, plus Update/Insert content if you want Claude to write. If you only grant Read, every write attempt fails with a permission error later – this is a common self-inflicted wound.
    4. Click Show, then copy the Internal Integration Token. New tokens start with ntn_ (older ones start with secret_ and still work). Treat it like a password.

    2. Add it to your MCP config

    For Claude Desktop, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\). Add:

    {
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_your_token_here"
      }
    }
  }
}

    Restart Claude Desktop completely (quit, do not just close the window). On Windows, if npx is not found, use the full path to npx.cmd or run via cmd /c – the config does not inherit your shell PATH.

    3. The step everyone forgets: share the pages

    An internal integration starts with access to nothing. Creating it and pasting the token is not enough. For every page or database you want Claude to touch, open it in Notion, click the … menu (top right), choose Connections (or Add connections), and select your integration. Access is inherited by child pages, so sharing a top-level page covers its whole subtree. Skip this and Claude will connect cleanly and then truthfully report that it cannot see any content.

    What are the most common Notion MCP errors and how do I fix them?

    These are the failure messages you will actually see, and what each one means.

    “Could not find page” / Claude returns zero results from a workspace that clearly has pages

    Cause, in order of likelihood: (1) you did not share the page with the integration (self-hosted), or you scoped the OAuth grant too narrowly (hosted); (2) the page is in a different workspace than the one the integration is tied to. Fix: re-check the Connections menu on the specific page, or re-run the OAuth flow and widen the page selection. An integration token is bound to one workspace – it cannot see another.

    API token is invalid (HTTP 401 unauthorized)

    The token is wrong, was regenerated, or has a stray space/newline from copy-paste. Re-copy it with the Show button, paste it into the env block with no surrounding whitespace, and restart the client. If you rotated the token in Notion, the old one dies immediately – update every config that used it.

    Validation error / “body failed validation” (HTTP 400)

    Claude tried to write a property type that does not match the database schema – for example sending plain text into a Select, or a malformed date. This is not a connection problem. Tell Claude the exact property names and types, or ask it to fetch the database schema first before writing.

    “Rate limited” / HTTP 429

    Notion enforces roughly 3 requests per second per integration (averaged, with short bursts tolerated). Bulk operations – “update 200 rows,” “scan every page” – blow straight through this. The fix is pacing, not a bigger plan: have Claude batch in small groups and add a short delay between calls. If you are scripting around the MCP, honor the Retry-After header on a 429 instead of hammering.

    spawn npx ENOENT (server will not start, self-hosted)

    Node/npx is not on the PATH the client sees. Install Node, then point command at the absolute path to npx (or npx.cmd on Windows). This is the number-one self-hosted startup failure.

    MCP server shows “failed” in claude mcp list right after adding it

    For the hosted server this almost always means OAuth was never completed – run /mcp and approve in the browser. For the self-hosted server it means the process crashed on launch; run the npx command manually in a terminal to see the real stack trace.

    What can Claude actually do with Notion once connected?

    With read + write capabilities granted, Claude can search your workspace, read pages and databases, create pages, append blocks, and update properties on existing rows. Practical things that work well: “summarize this Notion doc,” “create a row in my tasks database with these fields,” “find every page mentioning X and list the links,” “turn this conversation into a meeting-notes page.” Things that get awkward: very large pages (the response can get truncated – verify the write actually landed by fetching it back), and bulk edits that trip the rate limit. A reliable habit is to treat Notion as the source of truth and have Claude verify by re-fetching after any write, because timeouts on big pages can commit silently and still return a malformed response.

    Security notes from running this in production

    • Scope the OAuth grant tightly. The hosted connector inherits whatever you approve. If you only need one project area, share only that top-level page, not the whole workspace.
    • Never hardcode the token in a file you might commit. Keep ntn_ tokens in an env var or your OS secret store, and reference them from config. If a token leaks, revoke it in my-integrations immediately – revocation is instant.
    • Grant the minimum capability. If Claude only needs to read, do not enable insert/update. You can always widen it later.
    • Audit which integrations have access to sensitive databases periodically; the Connections menu on each page shows the current list.

    If you are wiring up several connectors at once, the mechanics generalize – see our broader Claude MCP setup guide for the config patterns that apply across servers, and the AI operator’s stack for how Notion fits alongside the other tools day to day. If your reason for connecting Notion is to get your own content cited by AI systems, the structure of the pages matters as much as the wiring – see how AI engines cite content.

    FAQ

    Do I need a paid Notion plan to use the MCP?

    No. The API and integrations work on free Notion workspaces. You do need to be a Workspace Owner to create an internal integration.

    Why does Claude say it connected but can’t find my pages?

    Almost always the page-sharing step. A self-hosted integration has access to nothing until you add it via the page’s Connections menu. For the hosted connector, you scoped the OAuth approval too narrowly – re-run it and select more pages.

    What is the Notion API rate limit?

    About 3 requests per second per integration, averaged over time with small bursts allowed. Exceeding it returns HTTP 429. Pace bulk operations and respect the Retry-After header.

    What does the ntn_ prefix mean on my token?

    It is the current internal integration token format. Tokens created today start with ntn_; older secret_ tokens still function and do not need to be replaced.

    Can the hosted Notion MCP run in a headless cron job?

    No. The hosted server requires interactive OAuth approval, which an unattended process cannot complete. Use the self-hosted npm server with an ntn_ token for headless automation.

    How do I let Claude write to Notion, not just read?

    Enable Update content and Insert content under the integration’s Capabilities (self-hosted), or approve write scope during OAuth (hosted). Read-only is the default and will reject every write with a permission error.

    Where do I put the Notion MCP config for Claude Desktop?

    In claude_desktop_config.json – ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows. Add a notion entry under mcpServers and fully restart the app.

    Can one integration access two workspaces?

    No. An internal integration is bound to the single workspace it was created in. For a second workspace, create a second integration (or a second OAuth grant on the hosted connector).

    Related reading from operators who run AI tooling daily: Claude Code vs Cursor, Claude Code vs Codex, and Claude in Chrome for LinkedIn automation.

    Frequently Asked Questions

    What is the Notion MCP server for Claude?

    The Notion MCP server is a connector that lets Claude read, search, and interact with your Notion workspace through the Model Context Protocol. With it connected, you can ask Claude to find pages, summarize databases, draft content into Notion, or retrieve information — all without copying and pasting anything manually.

    What is the difference between the Notion OAuth connector and the self-hosted token route?

    The OAuth connector (available in Claude Desktop’s built-in integrations) is the fastest path — authorize once and Claude gets read access to pages you share with the integration. The self-hosted route uses a Notion Internal Integration token in your claude_desktop_config.json, giving you more control over scopes and works in Claude Code environments where OAuth connectors aren’t available.

    Why does Claude say it can’t find my Notion pages after connecting?

    The most common reason is that you haven’t shared the specific pages or databases with your Notion integration. Notion’s permission model requires explicit page-level grants — a successful connection does not automatically give access to all your content. Go to the page in Notion, click the three-dot menu, choose ‘Add connections’, and select your integration.

    What scopes does the Notion MCP integration need?

    For read operations: Read content and Read user information. For write operations: Update content and Insert content. Avoid requesting more scopes than you need — the minimum set reduces the blast radius if a token is ever compromised. Set scopes when creating your Notion Internal Integration at notion.so/my-integrations.

    Does the Notion MCP integration work with Claude Code?

    Yes. Add it via ‘claude mcp add notion npx @notionhq/notion-mcp-server’ and set your NOTION_API_KEY as an environment variable. Claude Code picks it up on the next session. The self-hosted token route works in both Claude Desktop and Claude Code; the OAuth connector is currently Desktop-only.

    What rate limits does the Notion API have?

    Notion’s API enforces a rate limit of 3 requests per second per integration. For typical conversational use this is invisible, but if you ask Claude to crawl a large database or process many pages in sequence, you may see 429 errors. The fix is to add a short sleep between bulk operations or use Notion’s pagination to fetch in smaller batches.

    📖 Related Claude Guides


  • How to Connect Any Tool to Claude with MCP: Complete Setup Guide

    How to Connect Any Tool to Claude with MCP: Complete Setup Guide

    Last verified: June 2026

    MCP (Model Context Protocol) is how you give Claude hands. Out of the box Claude can talk; with an MCP server connected, it can read your files, query a database, hit an API, or drive a browser. This guide covers the two places you actually wire servers up: the claude_desktop_config.json file for the Claude Desktop app, and the claude mcp add command for Claude Code (the terminal/IDE tool). It ends with the troubleshooting section the official docs skip: path problems, JSON syntax traps, servers that silently never load, and the Windows quirks that cost people an afternoon.

    Everything below is checked against the current Claude Code MCP docs and tested commands. If you want the wider picture of how MCP fits into a working setup, see the AI operator’s stack.

    What is MCP and what is an MCP server?

    MCP transport options at a glance

    Transport Use case Config location Works with
    stdio Local tools, CLIs, scripts claude_desktop_config.json or claude mcp add Claude Desktop, Claude Code
    SSE (HTTP) Remote servers, cloud services URL in config Claude Desktop, Claude Code
    Streamable HTTP Production remote MCP URL in config Claude Desktop, Claude Code

    MCP is an open standard for connecting AI models to external tools and data. An MCP server is a small program that exposes a set of tools (functions Claude can call) over that protocol. Claude is the client; the server is the thing that actually does the work, like reading a Postgres table or creating a GitHub issue.

    There are two transport types you will deal with in practice:

    • stdio (local): the server runs as a process on your machine. Claude talks to it over standard input/output. Best for filesystem access, local databases, and custom scripts. This is what most “install this MCP server” instructions mean.
    • HTTP (remote): the server lives on the internet at a URL. Best for cloud services (Notion, Sentry, Stripe, GitHub). Often uses OAuth. SSE is the older remote transport and is now deprecated; use HTTP for new remote servers.

    The same server can usually be added to both Claude Desktop and Claude Code. The mechanics differ: Desktop uses a JSON file you edit by hand, Claude Code gives you a CLI that writes the config for you.

    How do I add an MCP server to Claude Desktop?

    Claude Desktop reads a single JSON file. You edit it, fully quit the app, and reopen. There is no in-app “add server” button for custom servers as of June 2026, so the file is the source of truth.

    Where is claude_desktop_config.json?

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json (paste that into the File Explorer address bar; it expands to C:\Users\YOU\AppData\Roaming\Claude\)

    The fastest way to open it: in Claude Desktop go to Settings > Developer > Edit Config. That button creates the file if it does not exist and opens the folder. If the file is brand new it may be empty or just {}.

    The config file structure

    Everything lives under a top-level mcpServers object. Each key is a name you choose; each value describes how to launch the server. Here is a complete, working file with a local filesystem server and a remote Notion server:

    {
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\YOU\\Documents"
      ]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "secret_your_token_here"
      }
    }
  }
}

    Three fields do all the work:

    • command the executable to run (npx, node, python, uvx, or an absolute path to a binary).
    • args an array of arguments. Each flag and value is its own array element. "--port 8080" as a single string will not work; use "--port", "8080".
    • env an object of environment variables (API keys, tokens). Optional.

    After saving, completely quit Claude Desktop (on Windows, right-click the system tray icon and choose Quit; closing the window is not enough) and reopen it. You should see a tools/connector indicator in the chat input. For a full Notion walkthrough including the token, see connecting Notion to Claude with MCP.

    How do I add an MCP server to Claude Code (CLI)?

    Claude Code does not make you hand-edit JSON. The claude mcp command manages servers for you and writes to the right file. This is the part people get wrong most often, so here is the exact, verified syntax.

    claude mcp add

    The general form for a local (stdio) server is:

    claude mcp add [options] <name> -- <command> [args...]

    The -- is load-bearing. Everything before it is for Claude Code; everything after it is the command that launches your server. Real examples:

    # Local filesystem server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Local server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server with an auth header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_PAT"

    Option ordering matters. All flags (--transport, --env, --scope, --header) must come before the server name. Put a flag after the name and you will get a confusing parse error or the flag will be passed to your server instead of to Claude Code.

    Scopes: local, project, user

    The --scope flag decides where the config is written and who sees it:

    • local (the default) loads only in the current project, private to you. Stored in ~/.claude.json keyed by the project path.
    • project loads in the current project and is shared with your team. Stored in a .mcp.json file at the project root that you commit to git.
    • user loads across all your projects, private to you. Also stored in ~/.claude.json.
    # Available across all your projects
claude mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

# Shared with your team via .mcp.json in the repo
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem .

    When the same server name exists at multiple scopes, local wins over project, which wins over user. The whole entry from the winning scope is used; fields are not merged.

    claude mcp list, get, and remove

    # List every configured server and its connection status
claude mcp list

# Show the full config for one server
claude mcp get github

# Remove a server
claude mcp remove github

    claude mcp list is your first diagnostic. It shows each server as connected, pending, or failed. Project-scoped servers from a .mcp.json you have not approved yet show as Pending approval until you run claude interactively and accept them.

    Other useful commands

    # Add from a raw JSON blob (handy when copying from a server's README)
claude mcp add-json weather '{"type":"stdio","command":"npx","args":["-y","weather-mcp"]}'

# Import everything you already set up in Claude Desktop (macOS / WSL)
claude mcp add-from-claude-desktop

    Inside a running Claude Code session, type /mcp to see live server status, tool counts, and to trigger OAuth login for remote servers that need it.

    Troubleshooting: the errors the docs skip

    Most MCP failures are not exotic. They are paths, quoting, and the app not restarting. Work this list top to bottom.

    Server not loading / no tools appear

    1. Did you actually restart? Claude Desktop only reads the config at launch. Fully quit (tray icon > Quit on Windows, Cmd+Q on macOS) and reopen. In Claude Code, run claude mcp list to see the real status instead of guessing.
    2. Is the command on PATH? The single most common stdio failure is npx, node, python, or uvx not being found by the app. GUI apps often have a narrower PATH than your terminal. Fix it by using an absolute path. Find it with which npx (macOS/Linux) or where npx (Windows), then put that full path in command.
    3. Read the logs. Claude Desktop writes per-server logs. macOS: ~/Library/Logs/Claude/. Windows: %APPDATA%\Claude\logs\. Look for mcp-server-NAME.log. The actual error (missing module, bad token, wrong path) is almost always sitting right there.

    spawn ENOENT or “command not found”

    This means the OS could not find the executable named in command. It is a PATH problem, not a Claude problem. Use the absolute path (see above). On Windows specifically, see the npx note below.

    JSON syntax errors (the silent killer)

    If claude_desktop_config.json has a single syntax error, Claude Desktop loads zero servers and usually says nothing. The usual culprits:

    • Trailing commas. JSON forbids a comma after the last item in an object or array. "args": ["a", "b",] is invalid.
    • Smart quotes. If you edited the file in a word processor, curly quotes (the slanted kind) break the parser. Use a code editor and straight quotes only.
    • Unescaped Windows backslashes. In JSON, \ is an escape character, so every backslash in a Windows path must be doubled: C:\\Users\\YOU\\Documents. A single backslash silently corrupts the string.

    Paste the whole file into any JSON validator before restarting. Thirty seconds there saves an hour of staring.

    Claude Code: flag passed to the wrong place

    If claude mcp add behaves strangely, you almost certainly put a flag after the server name or forgot the --. Reread the order: claude mcp add [flags] NAME -- COMMAND ARGS. The -- separates Claude Code’s flags from your server’s command.

    Windows quirks

    • npx needs a wrapper in some setups. If a bare "command": "npx" fails on Windows, launch it through cmd: "command": "cmd" with "args": ["/c", "npx", "-y", "the-server-package"]. This resolves a class of “npx works in my terminal but not in Claude” failures.
    • Use the right config root. It is %APPDATA%\Claude\ (which is AppData\Roaming), not AppData\Local. Mixing these up means you are editing a file the app never reads.
    • Git Bash mangles paths. If you run commands through Git Bash, it can rewrite paths like /c/Users or absolute paths inside arguments. Prefer PowerShell or cmd for claude mcp add, or pass paths exactly as Windows expects them.
    • WSL is a separate world. A server installed inside WSL is not visible to a Windows-native Claude Desktop, and vice versa. Keep both on the same side.

    Remote server returns 401 / 403

    The server needs authentication. In Claude Code, run /mcp and complete the OAuth flow in your browser. If you hardcoded an Authorization header and it is rejected, the token is wrong for that endpoint; remove the header and let OAuth handle it instead.

    Frequently asked questions

    What is an MCP server in one sentence?

    A small program that exposes tools (functions like read-file or query-database) to Claude over the Model Context Protocol, so Claude can take real actions instead of only producing text.

    What is the difference between Claude Desktop and Claude Code for MCP?

    Claude Desktop is the chat app and you configure servers by hand-editing claude_desktop_config.json, then restarting. Claude Code is the terminal/IDE tool and you configure servers with the claude mcp add command, which writes the config for you.

    Where is the Claude Desktop config file?

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. The quickest way to open it is Settings > Developer > Edit Config inside the app.

    Why is my MCP server not showing up?

    In order of likelihood: you did not fully restart the app, the command is not on the app’s PATH (use an absolute path), or there is a JSON syntax error such as a trailing comma, a smart quote, or an unescaped Windows backslash. Check the per-server log in the Claude logs folder for the exact error.

    What does the double dash do in claude mcp add?

    The -- separates Claude Code’s own flags from the command that launches your server. Flags like --transport and --env go before it; the actual launch command (npx -y some-server) goes after it.

    What is the default scope for claude mcp add?

    local. The server loads only in the current project and stays private to you. Use --scope user to make it available in every project, or --scope project to share it with your team via a committed .mcp.json.

    Is SSE or HTTP the right transport for remote servers?

    HTTP. SSE still works but is deprecated. Use --transport http for any new remote server unless its documentation specifically requires SSE.

    How do I remove an MCP server?

    In Claude Code, run claude mcp remove NAME. In Claude Desktop, delete that server’s entry from the mcpServers object in claude_desktop_config.json and restart the app.

    Where to go next

    Once your servers connect cleanly, the leverage comes from using them well. For how this fits a daily workflow, read the AI operator’s stack; if you are choosing between coding environments, see Claude Code vs Cursor. And if you want a concrete first server to wire up, the Notion MCP setup is a clean, high-value place to start.

    Frequently Asked Questions

    What is MCP and why does it matter for Claude?

    MCP (Model Context Protocol) is an open standard that lets Claude connect to external tools, databases, APIs, and services. Without MCP, Claude can only work with text in the conversation window. With an MCP server connected, Claude can read your files, query a live database, hit an API, or control a browser — turning it from a chat interface into an autonomous agent.

    How do I add an MCP server to Claude Desktop?

    Edit the claude_desktop_config.json file (found at ~/Library/Application Support/Claude/ on Mac, %APPDATA%/Claude/ on Windows). Add your server under the ‘mcpServers’ key with a ‘command’, ‘args’, and optional ‘env’ block. Save the file and restart Claude Desktop. The server appears in Claude’s tool list if it loaded correctly.

    How do I add an MCP server to Claude Code?

    Run ‘claude mcp add [args…]’ from your terminal. For a remote SSE server use ‘claude mcp add –transport sse ‘. List configured servers with ‘claude mcp list’. Servers added this way are scoped to your user profile unless you use the –project flag.

    Why does my MCP server connect but Claude can’t see my data?

    The most common cause is scope or permission gaps. For Notion, verify your integration has been granted access to the specific pages/databases — the connection succeeds even without page access. For file servers, check that the path in your config resolves correctly from the shell Claude launches (not your interactive shell). For OAuth servers, re-authorize and confirm token scopes.

    What is the difference between stdio and SSE MCP transports?

    stdio runs the MCP server as a local subprocess — Claude launches the command you specify and communicates over stdin/stdout. This is used for local tools and CLIs. SSE (Server-Sent Events) connects to a remote HTTP server. Use stdio for local tools like filesystem access or database clients; use SSE or Streamable HTTP for cloud services or shared team servers.

    Which MCP servers should I start with?

    The highest-value first connections are: filesystem (read/write your local files), a database client for your primary DB, and a service you interact with daily (Notion, Slack, GitHub, Linear). The Notion MCP server is a clean first project — see the dedicated setup guide on this site for the exact config and common errors.

    📖 Related Claude Guides


  • The Top Claude 4.6 Prompt for React Developers This Week

    The Top Claude 4.6 Prompt for React Developers This Week

    The Top Claude 4.6 Prompt for React Developers This Week

    If you are building front-end applications, you already know that Claude 4.6 Sonnet’s context window can handle massive files. But how do you prevent the model from ‘lazy coding’ (leaving // rest of code here comments)?

    The Anti-Lazy Prompt:

    “You are a Senior Staff Engineer. Rewrite this entire React component. Under NO circumstances are you allowed to use placeholders, comments like ‘// existing code’, or brevity. You must output the entire, complete, and fully functional file from line 1 to EOF. Failure to do so will break the CI/CD pipeline.”

    Why it works: By framing the omission as a pipeline-breaking failure, Claude’s alignment training prioritizes the completion of the file over token conservation.

  • Claude Artifacts API Release: What We Are Hearing

    Claude Artifacts API Release: What We Are Hearing

    The Claude “Artifacts” Wrapper is Coming to the Core API

    Anthropic’s “Artifacts” feature—which allows Claude to instantly render and preview code, diagrams, and UI elements in a side panel—has revolutionized the ChatGPT-style web interface. But for developers building their own applications using the Claude API, they’ve been forced to build those UI rendering wrappers from scratch.

    According to emerging chatter on X (Twitter), that is about to change.

    Social Radar Intel:
    “Rumors circulating that the Artifacts UI wrapper is finally coming to the core API next week. If developers can render interactive React components directly inside their own chat UIs using Claude, it’s game over for generic wrappers.”

    Why This Matters for Builders

    If Anthropic exposes the Artifacts rendering engine natively through the API, it significantly lowers the barrier to entry for building rich, interactive AI tools. You will no longer need a senior front-end engineer to parse JSON and render a React component on the fly; the API will handle the interactive framing.

    The Tygart Verdict: We are keeping a close eye on the official Anthropic changelog over the next two weeks. If this drops, expect a flood of “wrapper” apps to pivot or die.