Author: kongastral

When independent researchers first decompiled and analysed Claude Code—Anthropic’s AI-powered coding agent—many anticipated little more than a thin wrapper around a large language model. The reality proved considerably more involved. The system was found to comprise a sophisticated orchestration layer built from nineteen permission-gated tools, a streaming agent loop with continuous feedback, hierarchical memory systems, sub-agent spawning, context compaction algorithms, and a multi-layered permission model that governs every action the agent performs. The language model itself constitutes only one component of a substantially larger system.

This observation crystallised a position that the AI engineering community had been approaching for some time: the model is not the product. The harness is. The thousands of lines of orchestration code surrounding a language model—determining what it sees, what it may do, how it recovers from mistakes, and how it preserves knowledge across sessions—is where the engineering effort concentrates, and where quality is ultimately gained or lost.

Consider a simple thought experiment. Two developers are given the same LLM API key. One constructs a basic prompt-and-response loop. The other assembles a system with tool access, automated testing, iterative error correction, and persistent project memory. Both rely on the same underlying model, yet the outcomes diverge sharply. The decisive factor is not the engine but everything constructed around the engine. The decisive factor is the harness.

As large language models become increasingly commoditised—with open-source models narrowing the gap on proprietary systems and multiple providers offering comparable capability—the harness surrounding the model is rapidly emerging as the principal competitive advantage. Organisations that develop expertise in harness design will build agents that reliably ship code, manage infrastructure, and automate complex workflows. Organisations that treat the model as the entire product will find their agents repeatedly failing on real-world tasks. The remainder of this article examines harness engineering in detail: its definition, its implementation within Claude Code, and the steps required to build one independently.

What Is Harness Engineering?

The definition used by Anthropic’s engineering team is a useful starting point: harness engineering is “the art and science of using a coding agent’s configuration points to improve output quality and increase task success rates.” It is the discipline of designing, building, and refining every component of an AI agent except the model itself.

The underlying formula is straightforward:

An analogy clarifies the relationship. The model is an engine—a powerful, general-purpose engine capable of generating text, reasoning about code, and solving complex problems. An engine on a workbench, however, travels nowhere. It cannot steer, brake, or recognise a destination. The harness is the vehicle constructed around that engine: the steering wheel (guides that direct the model’s behaviour), the brakes (permissions that prevent harmful actions), the transmission (tools that translate model decisions into real-world actions), the navigation system (context management that keeps the model oriented), and the safety systems (verification and correction loops that detect and remediate errors).

An engine alone accomplishes little. A vehicle without an engine cannot move at all. Both components are necessary, but when comparing two vehicles with equivalent engines, the one with superior surrounding engineering will consistently prevail.

Why Harness Engineering Matters

The same model paired with a poorly designed harness produces unreliable results. The same model paired with a well-designed harness produces consistently strong results. The effect is measurable rather than theoretical. Anthropic’s research on long-running coding agents demonstrated that harness improvements—better guides, tighter feedback loops, more refined context management—increased task success rates by a factor of two to three without any change to the underlying model. The model was already capable of solving the problems; the harness was the bottleneck.

This observation marks a fundamental shift in how AI engineering is conceived. For several years, the dominant paradigm has been prompt engineering—the craft of writing better prompts to elicit better outputs from language models. Prompt engineering is valuable, but it constitutes a single-turn optimisation: a prompt is crafted, a response is received, and the prompt is revised. Harness engineering represents the evolution of prompt engineering into a full systems discipline. It encompasses not only the prompt but the tools available to the model, the verification steps executed after the model acts, the correction mechanisms triggered when problems arise, the memory systems that persist knowledge across sessions, and the permission boundaries that keep the agent safe.

Prompt engineering asks how to write a better prompt. Harness engineering asks how to build a better system around the model such that it reliably succeeds at complex, multi-step, real-world tasks.

The Four Core Functions of a Harness

Anthropic’s published research on effective agent harnesses identifies four core functions that every harness must perform. These functions may be regarded as the four pillars supporting a reliable AI agent. Removing any one of them causes the structure to become unstable. Each is examined in turn below.

Guides (Feedforward Controls)

Guides function as feedforward controls: they steer the agent before it acts. Their purpose is to set expectations, provide context, establish rules, and shape the model’s behaviour before it produces a line of code or executes a command. Effective guides substantially reduce errors by preventing them at the outset rather than catching them after the fact.

Within the Claude Code ecosystem, guides take several concrete forms:

• CLAUDE.md files: Project-level instruction files that inform the agent about the codebase, coding conventions, the frameworks to use, the patterns to follow, and the mistakes to avoid. These are the single most impactful harness component a practitioner can configure.
• Custom commands (slash commands): Pre-defined workflows like /write-post or /review that structure multi-step tasks into repeatable processes, complete with specific instructions for each step.
• Coding conventions and style guides: Explicit rules about formatting, naming, architecture patterns, and anti-patterns that the agent should follow or avoid.
• Structured prompts and bootstrap instructions: System-level prompts that establish the agent’s role, capabilities, and constraints before any user interaction begins.
• Task decomposition rules: Instructions that tell the agent how to break down large tasks into manageable subtasks, preventing the common failure mode of trying to do too much in a single step.
• Examples and few-shot demonstrations: Concrete examples of desired output that show the agent exactly what “good” looks like for a given task.

The principal observation about guides is that they are inexpensive to implement and high-impact. A thorough CLAUDE.md file can be written in approximately thirty minutes, and the resulting improvement in agent output quality is often substantial and immediate. For this reason, Anthropic recommends that practitioners begin their harness engineering work with guides.

Sensors (Feedback Controls)

Sensors are feedback controls: they detect problems after the agent acts. Whereas guides seek to prevent errors, sensors accept that errors will occur and focus on detecting them quickly. The earlier an error is detected, the less costly it is to remediate.

Effective sensors for AI coding agents include the following:

• Linters (ESLint, Ruff, mypy, Pylint) tuned for LLM-generated code patterns—LLMs tend to make specific categories of mistakes that linters can catch reliably.
• Type checkers that catch type errors, missing imports, and interface mismatches before runtime.
• Test suites designed specifically for LLM output patterns, not just generic unit tests, but tests that target the kinds of errors AI agents commonly make.
• Build verification that ensures the code compiles and the project builds successfully after every change.
• Code diff analysis that reviews what changed and flags potentially problematic patterns (accidental deletions, overly broad changes, unintended side effects).

Verification

Verification extends beyond sensors. Whereas sensors detect that something may be wrong, verification confirms that the agent has accomplished the intended objective. It addresses questions of whether the feature functions as required, whether the output matches the specification, and whether the behaviour is substantively correct rather than merely syntactically valid.

Verification mechanisms include the following:

• Automated test execution: Running the full test suite (or relevant subset) after changes to confirm that existing functionality still works and new functionality behaves as specified.
• CI/CD pipeline integration: Feeding agent output through the same continuous integration pipeline that human code goes through, ensuring equal quality standards.
• Browser automation testing: For web applications, actually loading the page and verifying that UI changes render correctly—not just checking that the code is syntactically valid, but that it produces the right visual and interactive result.
• LLM-as-a-Judge: Using a superior model (or the same model in a separate context) to evaluate the quality and correctness of the agent’s output. This is particularly useful for subjective quality assessments like code readability, documentation quality, or design decisions.

Correction

Correction is the final pillar, and arguably the function that distinguishes prototype agents from production-grade agents. When the agent makes a mistake—and it inevitably will—the response of the system determines its utility. A naive system simply fails and reports the error. A well-designed harness returns the error to the model, allows it to reason about the cause, generates a corrective action, and retries.

Correction mechanisms include the following:

• Feedback loops: Test failure → model reads the error message → model analyzes the root cause → model generates a fix → system reruns the test. This loop can repeat multiple times until the test passes or a retry limit is reached.
• Self-repair mechanisms: When the agent detects that its own output is malformed or incomplete, it can trigger a repair pass without human intervention.
• Retry logic with context: Not just blindly retrying the same action, but retrying with additional context about what went wrong, the error message, the stack trace, the failing test output.
• Graceful fallback strategies: When the agent cannot solve a problem after multiple attempts, it should degrade gracefully—perhaps simplifying its approach, asking for human input, or documenting what it tried and why it failed.

The interplay among these four functions produces a resilient system. Guides reduce the error rate. Sensors catch errors that slip through. Verification confirms that the overall objective has been achieved. Correction addresses cases in which it has not. Together, these functions transform a probabilistic language model into a system reliable enough for production use.

Inside Claude Code’s Harness Architecture

With the theoretical framework established, attention can now turn to how one of the most sophisticated AI coding agents currently available implements these principles. Claude Code is not simply a model attached to a terminal; it is a carefully engineered harness that embodies all four core functions. Based on public analysis of its architecture, the following components are observable.

19 Permission-Gated Tools

At the centre of Claude Code’s harness sit nineteen distinct tools that the model can invoke to interact with the outside world. Each tool is permission-gated, meaning that the system controls which tools the agent may use and under what circumstances. The tools include the following categories:

• File I/O: Read (view file contents), Write (create or overwrite files), Edit (make targeted string replacements in existing files)
• Shell execution: Bash (execute arbitrary shell commands with timeout controls)
• Search: Grep (content search with regex support), Glob (file pattern matching)
• Git operations: Integrated version control operations
• Web access: WebFetch (retrieve web page content for research)
• Notebook editing: NotebookEdit (modify Jupyter notebook cells)
• Sub-agent spawning: Agent (create specialized sub-agents for parallel or delegated tasks)
• Task management: TaskCreate, TaskGet, TaskList, TaskUpdate (manage background tasks)

The important design decision here is permission gating. Not all tools carry equivalent risk. Reading a file is safe; deleting a file is potentially harmful; running an arbitrary shell command may have any number of consequences. Claude Code’s harness categorises tool invocations by risk level and requires explicit user approval for high-risk operations, such as executing unfamiliar shell commands, writing to sensitive files, or performing destructive git operations. This corresponds to the braking system in the vehicle analogy, and it is essential for establishing trust.

The Streaming Agent Loop

In contrast to a simple request-response chatbot, Claude Code operates in a streaming agent loop. The model receives input, reasons about an appropriate action, invokes a tool, observes the result, reasons again, invokes a further tool, and continues this cycle until the task is complete or human input is required. This loop is what qualifies Claude Code as an agent rather than a chatbot.

The streaming nature of this loop is significant for user experience. Rather than disappearing for extended periods of internal processing, the agent presents its work in real time: the user can observe the files being read, the commands being executed, and the decisions being made. This transparency builds trust and allows the user to intervene early when the agent is proceeding in an undesirable direction.

Context Management Layer

One of the most underappreciated components of Claude Code’s harness is its context management layer. Language models have finite context windows, even when those windows are large. A coding session that involves reading dozens of files, running tests, making changes, and debugging errors can rapidly exceed the available context. Claude Code addresses this constraint through several mechanisms:

• Auto-compaction: When the conversation approaches the context limit, the harness automatically summarizes earlier parts of the conversation, preserving the most important information while freeing up context space for new work.
• Persistent memory: The CLAUDE.md system and memory files allow important information to persist across sessions, so the agent does not need to re-learn the project’s conventions every time it starts.
• Selective file reading: Rather than loading entire files, the agent can read specific line ranges, search for specific patterns, and load only the relevant portions of large files.

The CLAUDE.md System

Claude Code’s CLAUDE.md system is a hierarchical instruction framework that operates at multiple levels:

• Project-level CLAUDE.md: Lives in the repository root. Contains project-specific instructions, coding conventions, architecture descriptions, and common pitfalls. Every developer on the team benefits from the same instructions.
• User-level CLAUDE.md: Lives in the user’s home directory. Contains personal preferences and conventions that apply across all projects.
• Directory-level CLAUDE.md: Lives in specific subdirectories. Contains instructions specific to that part of the codebase, useful for monorepos or projects with distinct subsystems.

This hierarchy means the agent receives increasingly specific guidance as it descends into the codebase. The project-level file might specify the use of TypeScript with strict mode. The directory-level file in /src/database/ might add an instruction to always use parameterised queries and never string concatenation for SQL. The system merges these instructions, with more specific files taking precedence.

Hooks and MCP Integration

Two additional harness components warrant mention. Hooks are shell commands that execute automatically in response to agent events. For example, a pre-tool hook may run a linter before every file write, or a post-tool hook may validate the result of every shell command. Hooks allow automated quality gates to be injected into the agent’s workflow without modifying the agent itself.

MCP (Model Context Protocol) integration allows Claude Code to connect to external tools and data sources through a standardised protocol. MCP servers can provide access to databases, APIs, project management tools, documentation systems, and any other resource that might assist the agent. This component functions as the expansion port of the harness: the mechanism for extending capabilities beyond the built-in tools.

Multi-Agent Harness Architecture

One of the most significant findings from Anthropic’s research on long-running agents is that the optimal harness architecture for complex tasks is not a single agent performing every function, but rather multiple specialised agents, each operating with a clean context and a focused role. This is the multi-agent harness pattern, and it addresses one of the most persistent problems in AI agent design: context degradation.

The Context Degradation Problem

The problem can be stated as follows. A single agent working on a large task accumulates context over time—files it has read, commands it has run, errors it has encountered, and decisions it has made. As this context grows, the model’s ability to maintain focus and coherence degrades. Anthropic’s research refers to this phenomenon as “context anxiety”: the model becomes increasingly uncertain about which information remains relevant, begins to second-guess earlier decisions, and may even contradict its own prior work. The longer the session, the more pronounced the effect.

The multi-agent pattern resolves this difficulty by providing each agent with a clean context reset. Instead of a single agent performing all functions, specialised agents each handle one phase of the work, passing structured handoffs between them.

The Planner-Generator-Evaluator Pattern

Anthropic’s research describes an effective three-agent pattern:

• Planner Agent: Takes a brief user prompt and expands it into a comprehensive specification. The planner reads the codebase, interprets the requirements, and produces a detailed plan that includes which files require modification, what the expected behaviour should be, and which edge cases warrant consideration. The planner does not write code; it writes specifications.
• Generator Agent: Takes the planner’s specification and implements it. The generator writes code, creates tests, makes file changes, and runs builds. It works iteratively—implementing a component, testing it, addressing issues, and proceeding to the next component. The generator operates with a clean context that has not been encumbered by the planner’s exploration and deliberation.
• Evaluator Agent: Takes the generator’s output and conducts quality assurance. The evaluator reviews the code for correctness, style, security issues, and specification compliance. It runs tests, checks for regressions, and provides a final assessment, again from a clean context focused exclusively on evaluation.

Each agent receives a fresh context window and operates within a clear, focused role. The handoffs between agents consist of structured data—specifications, code diffs, test results—rather than the growing conversation of a single long-running session.

How Claude Code Implements Multi-Agent Patterns

Claude Code implements this pattern through its Agent tool, a built-in capability for spawning sub-agents. When Claude Code encounters a task that would benefit from delegation, it can create a sub-agent with a specific prompt and a clean context. The sub-agent runs independently, completes its task, and returns its results to the parent agent.

This approach is particularly suitable for tasks such as the following:

• Searching a large codebase while the main agent continues to reason about the overall task
• Running a battery of tests while the main agent plans the next change
• Investigating a complex error in a separate context so that the investigation does not contaminate the main workflow
• Reviewing code changes against project standards before the main agent marks the task as complete

When to Use Single-Agent vs Multi-Agent

A single agent is appropriate when the task can be completed within one context window, the requirements are clear, and the feedback loop is tight—writing code, running tests, fixing issues, and repeating. Most routine coding tasks fall into this category.

A multi-agent configuration is warranted when the task is sufficiently large that context degradation becomes a genuine concern, when different phases of the task require fundamentally different skill sets (planning, implementation, and review), or when parallel execution of independent subtasks is required. Large feature development, codebase migrations, and comprehensive code reviews are appropriate candidates.

How to Engineer Your Own Harness for Claude Code

Theory has its place, but practical guidance is essential. The following discussion outlines the five levels of harness engineering for Claude Code, ranging from the simplest configuration to advanced multi-agent orchestration. Each level builds on the previous one, and practitioners should begin at Level 1 and add complexity only when a specific problem cannot be addressed at the current level.

Level 1: CLAUDE.md (The Foundation)

The single most impactful action a practitioner can take to improve Claude Code’s performance on a project is to write a comprehensive CLAUDE.md file. This file serves as the foundation upon which everything else is built.

An effective CLAUDE.md includes the following elements:

• Project purpose: The function of the project, its users, and the problem it addresses.
• Technology stack: Languages, frameworks, databases, and deployment targets.
• Coding conventions: Formatting rules, naming conventions, and architectural patterns.
• File structure: The location of project components and the contents of each directory.
• Key commands: Procedures for building, testing, deploying, and running the project.
• Items to avoid: Common mistakes, anti-patterns, and prohibited practices. This is often the most valuable section.

An example CLAUDE.md for a Python project is shown below:

# Project: DataPipeline

## Purpose
ETL pipeline that processes financial data from multiple exchanges
and loads it into our PostgreSQL analytics database.

## Tech Stack
- Python 3.12, managed with uv
- SQLAlchemy 2.0 for database access
- Pydantic for data validation
- pytest for testing
- Ruff for linting

## Key Commands
- Run tests: `uv run pytest tests/ -v`
- Lint: `uv run ruff check src/`
- Run pipeline: `uv run python -m src.main run --date 2026-04-03`

## Coding Conventions
- All functions must have type hints
- Use Pydantic models for all data structures (no raw dicts)
- SQL queries use parameterized queries only (never f-strings)
- Test files mirror source structure: src/foo/bar.py → tests/foo/test_bar.py

## What NOT to Do
- Do not use pandas — we use Polars for dataframes
- Do not hardcode database credentials — use environment variables
- Do not write raw SQL strings — use SQLAlchemy ORM
- Do not skip type hints — mypy strict mode is enforced in CI

With this single file present in the repository root, Claude Code will produce code that follows the project’s conventions, uses the specified tools, and avoids known pitfalls. No additional configuration is required.

Level 2: Custom Commands (Task Automation)

Custom commands allow repeatable workflows to be defined as slash commands. They reside in .claude/commands/ as Markdown files, and each file becomes a command that can be invoked with /command-name.

An example .claude/commands/write-tests.md is shown below:

Write comprehensive tests for the file or module specified in $ARGUMENTS.

## Steps:
1. Read the source file and understand its public API
2. Identify all functions, classes, and methods that need testing
3. Write pytest tests covering:
   - Happy path for each function
   - Edge cases (empty inputs, None values, boundary conditions)
   - Error cases (invalid inputs, missing dependencies)
4. Save tests to the mirror path: src/foo/bar.py → tests/foo/test_bar.py
5. Run the tests: `uv run pytest tests/foo/test_bar.py -v`
6. Fix any failing tests
7. Run the linter: `uv run ruff check tests/foo/test_bar.py`
8. Report results

With this command in place, a user can type /write-tests src/pipeline/transformer.py and Claude Code will follow this exact workflow each time. Testing conventions do not need to be re-explained in every conversation. The command encodes the team’s standards into a repeatable process.

Other useful custom commands worth considering include /review for code review, /deploy for deployment workflows, /debug for structured debugging sessions, and /refactor for refactoring with specific quality gates.

Level 3: Hooks (Automated Quality Gates)

Hooks allow automated checks to be injected into Claude Code’s workflow. They consist of shell commands that execute in response to specific events—before a tool runs, after a tool runs, or at other key moments in the agent loop.

An example hook configuration in .claude/settings.json is shown below:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "uv run ruff check --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "PreCommit": [
      {
        "command": "uv run pytest tests/ -x -q 2>&1 | tail -5"
      }
    ]
  }
}

With this configuration, every time Claude Code writes or edits a file, Ruff automatically runs and corrects formatting issues. Before every commit, the test suite runs and the results are returned to the agent. These constitute automated sensors and verification gates: they execute without human intervention and without requiring the agent to remember to invoke them.

Level 4: MCP Servers (External Integration)

MCP (Model Context Protocol) servers extend Claude Code’s capabilities by connecting it to external tools and data sources. They are configured in .claude/settings.json and appear as additional tools that the agent can use.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

With MCP servers configured, Claude Code can query a database directly (understanding schema, running queries, and verifying data), interact with GitHub (creating pull requests, reading issues, and checking CI status), and integrate with any other tool that provides an MCP server implementation. This transformation moves Claude Code from a coding assistant to an integrated development environment that understands the entire infrastructure.

Level 5: Multi-Agent Orchestration

At the highest level of harness sophistication, multi-agent workflows can be orchestrated in which different Claude Code instances handle different phases of a task. This can be accomplished through custom commands that explicitly invoke the Agent tool for delegation.

A conceptual example of a /feature command implementing the planner-generator-evaluator pattern is shown below:

Implement the feature described in $ARGUMENTS using a
multi-phase approach:

## Phase 1: Planning
Use the Agent tool to spawn a planning sub-agent with this prompt:
"Read the codebase and create a detailed implementation plan for:
$ARGUMENTS. List all files to modify, new files to create,
tests to write, and edge cases to consider. Output a structured
specification."

## Phase 2: Implementation
Use the Agent tool to spawn an implementation sub-agent with
the specification from Phase 1. The sub-agent should implement
the feature, write tests, and run them.

## Phase 3: Review
Use the Agent tool to spawn a review sub-agent that reads the
diff of all changes, checks for bugs, security issues, style
violations, and specification compliance. Report any issues found.

## Phase 4: Resolution
If the review found issues, fix them. Run the full test suite.
Report the final result.

Each sub-agent operates with a clean context focused on its specific phase, while the parent agent coordinates the workflow and manages the handoffs.

Harness Engineering Best Practices

After considerable time building and refining harnesses for Claude Code, several best practices emerge. These are not theoretical recommendations but lessons drawn from extensive practical experience.

Begin Simply and Add Complexity Only When Required

The most common mistake in harness engineering is over-engineering from the outset. Hooks, MCP servers, and multi-agent orchestration are not required on the first day. The recommended starting point is a CLAUDE.md file. After a week of using Claude Code, recurring errors will become apparent. A custom command or guide should then be added to address that specific failure pattern, and the process iterated. The most effective harnesses are grown organically from observed failure patterns rather than designed top-down from theoretical requirements.

Make the Harness Project-Specific

A one-size-fits-all harness is invariably a mediocre harness. A Python data pipeline has different requirements from a React frontend, which in turn has different requirements from a Rust systems library. The CLAUDE.md, custom commands, and hooks should all be tailored to the specific project, its technology stack, its conventions, and its common failure modes. Generic guidance such as “write clean code” is of little use. Specific instructions such as “use Pydantic models for all API responses; never return raw dicts” are actionable.

Test the Harness Configuration

One practice that distinguishes competent harness engineers from highly effective ones is the A/B testing of harness changes. Before adding a new guide or hook, a representative task should be run and the result recorded. The harness change is then applied and the same task executed again. The improvement, if any, should be quantified. This empirical approach prevents harness bloat—configurations that appear useful but do not actually improve outcomes.

Place the Harness Under Version Control

The CLAUDE.md file, the .claude/commands/ directory, and the hooks configuration should all be checked into version control alongside the code. They form part of the project’s engineering infrastructure and should be reviewed in pull requests, iterated upon over time, and shared across the team. A harness that exists only on one developer’s machine is a harness that will eventually be lost.

Iterate Based on Failure Patterns

Each time Claude Code makes a mistake that it should not have made, the question to ask is whether a harness change could have prevented it. If the agent repeatedly uses the wrong database library, a guide should be added. If it repeatedly forgets to run tests, a hook should be added. If it repeatedly generates code that fails the linter, a sensor should be added. The harness should function as a living document that evolves as new failure patterns are identified.

Balance Autonomy and Control

Excessive constraints render the agent slow and inflexible, as it spends more time verifying rules than completing work. Insufficient constraints render it error-prone, as it makes avoidable mistakes from lack of guidance. The appropriate balance varies by project and team. High-risk production codebases require more constraints, while experimental prototyping projects benefit from greater autonomy. Calibration should be adjusted accordingly.

Monitor and Measure

The agent’s success rate should be tracked over time. Relevant questions include how often the agent completes tasks correctly on the first attempt, how often correction is required, and which categories of errors occur most frequently. This data indicates where to direct harness engineering effort. If eighty per cent of failures are type errors, investment in type-checking sensors is warranted. If eighty per cent of failures stem from misunderstood requirements, investment in better guides is warranted.

Harness Engineering vs Prompt Engineering

Harness engineering is sometimes conflated with prompt engineering. Although the two are related, they are fundamentally different disciplines, and understanding the distinction is important for allocating engineering effort appropriately.

Prompt engineering is the craft of writing a single prompt for a single interaction. It focuses on wording, structure, few-shot examples, and instruction clarity in order to obtain the best possible response from one model call. It is valuable, and it constitutes one component of harness engineering—specifically, it falls under the heading of guides. But it remains only one piece of a broader framework.

Harness engineering is the discipline of designing a complete system around the model for sustained, reliable operation across many interactions and many tasks. It encompasses not only the prompt but every other component: the tools the model can use, the verification that runs after the model acts, the correction mechanisms invoked when problems arise, the persistence of cross-session knowledge, and the permissions that govern what the model may do.

The principal observation is that prompt engineering is a subset of harness engineering. A practitioner who attends only to prompt engineering leaves the majority of available improvement potential unrealised. The largest gains derive from the components that prompt engineering does not address: tools, verification, correction, and persistence.

Real-World Harness Examples

Abstract principles are useful, but concrete examples render them actionable. Three real-world harness configurations are presented below to demonstrate the principles in practice.

Example 1: Blog Publishing Harness (aicodeinvest.com)

The reader is currently engaging with the output of such a harness. This article was written and published by Claude Code operating within a harness developed specifically for blog publishing. The harness includes the following components:

• CLAUDE.md: Contains writing guidelines (4,000-6,000 words, measured tone, specific HTML patterns), post structure requirements (Table of Contents, Introduction, body sections, Conclusion, References), and explicit anti-patterns to avoid (no numbered headings, no html/head/body wrappers).
• /write-post custom command: Orchestrates the full workflow, including topic selection, writing, saving, publishing via WordPress REST API, and recording topic usage for deduplication.
• WordPress REST API as a tool: A Python CLI (src/main.py) that handles authentication, content upload, category assignment, and status management.
• Topic deduplication system: Tracks recently used topics in config/recent_topics.json to prevent the agent from writing about the same subject twice.

This harness transforms Claude Code from a general-purpose AI assistant into a specialised blog publishing system. The model’s writing ability provides the engine. The harness—comprising the CLAUDE.md guidelines, the custom command workflow, the publishing tools, and the deduplication system—is what converts that engine into a reliable content production pipeline.

Example 2: Enterprise Code Review Harness

Consider a team using Claude Code for automated code review. The corresponding harness might include the following components:

• CLAUDE.md: Company coding standards, security requirements (no hardcoded secrets, all inputs sanitised, all queries parameterised), performance guidelines (no N+1 queries, pagination required for list endpoints), and architectural rules (clean architecture layers, dependency injection).
• /review custom command: A structured review process that checks security, performance, style, test coverage, and documentation in that order, producing a formatted review with severity ratings.
• CI/CD integration hooks: Post-commit hooks that run the test suite, linter, and security scanner, returning results to the agent for review.
• Jira/Linear MCP server: Connects Claude Code to the team’s project management tool, enabling it to read ticket descriptions, interpret acceptance criteria, and verify that code changes match the specified requirements.

This harness ensures that every code review follows the same rigorous process, applies the same standards, and produces consistent, actionable feedback regardless of which developer triggered the review or which part of the codebase is under modification.

Example 3: Data Pipeline Harness

A data engineering team might construct a harness for managing ETL pipelines:

• Custom commands: /new-pipeline for scaffolding new ETL jobs with the team’s standard structure, /validate-schema for checking data schemas against the warehouse, and /backfill for running historical data loads with appropriate idempotency checks.
• Database MCP server: Provides Claude Code with direct access to the data warehouse schema, allowing it to interpret table structures, column types, relationships, and constraints without explicit explanation from the developer.
• Test data generation tools: Custom commands that generate realistic test data for pipeline testing, including edge cases such as null values, duplicate records, and timezone mismatches.
• CLAUDE.md with data engineering conventions: Rules concerning idempotency (all pipelines must be safely re-runnable), data validation (all inputs must be schema-validated before processing), and monitoring (all pipelines must emit metrics for latency, throughput, and error rate).

Each of these examples illustrates the same principle: the harness is tailored to the specific domain, encoding domain expertise into configuration that the agent can apply automatically.

The Future of Harness Engineering

Harness engineering is a young discipline that is evolving rapidly. Several trends are discernible.

A New Engineering Discipline

Just as DevOps emerged as a distinct discipline at the intersection of development and operations, harness engineering is emerging as a distinct discipline at the intersection of AI and software engineering. Companies are already hiring for roles that are, in effect, harness engineering positions—specialists in configuring, tuning, and optimising AI agent systems. The formal title may be “AI Platform Engineer” or “Agent Systems Engineer,” but the core skill set is harness engineering.

Standardisation Through MCP

The Model Context Protocol (MCP) represents the first serious attempt to standardise the interface between AI agents and external tools. Prior to MCP, each agent maintained its own proprietary tool integration system. MCP provides a common protocol that any tool can implement and any agent can consume. The analogy with HTTP and the web is apt: a standard creates the conditions for an ecosystem. As MCP matures, MCP servers can be expected to proliferate across the full range of tools and data sources, substantially lowering the cost of harness engineering.

Harness Marketplaces

At present, sharing a harness configuration involves distributing CLAUDE.md files and custom commands through GitHub repositories. In the future, dedicated marketplaces for harness configurations may emerge—curated collections of CLAUDE.md files, custom commands, hooks, and MCP server configurations for specific technology stacks and workflows. Examples might include production-ready harnesses for Django with PostgreSQL and Celery, or for iOS development with SwiftUI and Core Data. Such pre-built harnesses would provide teams with a starting point that already encodes best practices for their stack.

Self-Improving Harnesses

The most consequential frontier is the development of self-improving harnesses: harness systems that learn from their own failures and automatically update their configuration. A harness might, for example, observe that the agent repeatedly makes the same type error in a specific module and automatically add a guide to CLAUDE.md stipulating the use of Decimal rather than float for monetary values in the payments module. Alternatively, a harness might detect that test failures cluster around a specific API endpoint and automatically add more thorough validation for the responses from that endpoint.

This is not speculative. The constituent building blocks exist today. The agent can read its own CLAUDE.md, analyse its own failure patterns, and edit its own CLAUDE.md. The missing element is the orchestration logic that determines when to perform such updates and what to change. This is an active area of research.

The “Operating System for AI” Vision

At a sufficient level of abstraction, the harness begins to resemble an operating system. It manages resources (context windows, tool access), enforces permissions (what the agent may and may not do), provides system services (file I/O, networking, process management), and exposes a user interface (the conversation loop). The analogy is imperfect, but it points toward a future in which the harness is not merely a configuration layer but a complete runtime environment for AI agents, exhibiting the level of sophistication that operating systems bring to traditional computing.

Final Thoughts

The AI industry has spent the past several years in a competition over models—larger, faster, more capable. That competition continues, but a parallel race has emerged: the race to build better harnesses. The teams and organisations that develop expertise in harness engineering will extract substantially more value from the same models available to everyone else.

The formula is straightforward: Agent = Model + Harness. The model provides raw intelligence. The harness provides structure, tools, verification, correction, memory, and control. Together, they produce an agent capable of operating reliably in the real world. Separately, neither is complete.

If one observation should be drawn from this article, it is the following: an AI agent should not be treated as a chatbot with additional features but as an engineered system. A CLAUDE.md file should be written. Custom commands should be created for common workflows. Hooks should be added for automated quality gates. MCP servers should be connected for external tool access. The harness should be tested, iterated upon, placed under version control, and shared across the team.

The model is the engine. The harness is the vehicle. At present, many practitioners are attempting to drive an engine across the motorway. The vehicle must be built.

References

• Anthropic Engineering—“Harness design for long-running application development”
• Anthropic Engineering—“Effective harnesses for long-running agents”
• Martin Fowler,“Harness engineering for coding agent users”
• HumanLayer—“Skill Issue: Harness Engineering for Coding Agents”
• Anthropic—Claude Code Documentation
• Anthropic,Model Context Protocol (MCP) Specification

Introduction

Consider a manufacturing engineer monitoring an assembly line that produces ten thousand circuit boards per day. Of those ten thousand, perhaps three are defective. A machine learning model must catch those three, yet the available data consists overwhelmingly of examples of good boards, with very few examples of defective ones. The choice is between waiting months to collect sufficient defective samples and building a model that learns the structure of “normal” and flags everything else.

This dilemma marks the fundamental divide between two of the most important algorithms in machine learning: the Support Vector Machine (SVM) and its less widely recognised counterpart, the One-Class SVM (OCSVM). Despite a shared name and mathematical lineage, the two algorithms address fundamentally different problems. SVM is a supervised classifier that draws a boundary between two labelled groups. OCSVM is a semi-supervised anomaly detector that wraps a boundary around a single group and treats any point falling outside it as suspicious.

Choosing the wrong method has serious consequences. Applying SVM in the absence of labelled anomalies prevents the model from training at all. Applying OCSVM to perfectly balanced, labelled data discards half of the available information. Yet in tutorials across the internet, the two are routinely conflated, treated cursorily, or illustrated with identical toy examples that obscure their substantive differences.

The present article addresses these gaps. Both algorithms are presented from first principles, with inline SVG diagrams that render the geometry visible. The mathematics is covered with sufficient depth but without excess, and complete runnable Python implementations of both algorithms are provided. A practical decision framework follows, intended to support correct method selection. The treatment is suitable both for a data scientist choosing between approaches in a fraud detection system and for a student aiming to understand when single-class modelling is appropriate.

What Is SVM (Support Vector Machine)?

The Support Vector Machine is one of the more elegant algorithms in machine learning. Developed in the 1990s by Vladimir Vapnik and colleagues at AT&T Bell Labs, SVM is a supervised binary classifier that identifies the optimal hyperplane—a decision boundary—that separates two classes of data with the maximum possible margin.

The intuition is as follows. Consider a scatterplot with blue points on one side and red points on the other. Infinitely many lines could separate them. SVM selects the line that sits as far as possible from the nearest points of both classes. Those nearest points are termed support vectors, and they support the position of the boundary in a literal sense: removing them shifts the boundary. All other points in the dataset are irrelevant to the final model.

Visualising the Standard SVM

The following diagram shows how SVM operates in two dimensions. The decision boundary (solid line) sits exactly between the two classes, with the margin (the gap between the dashed lines) maximised:

This is the central insight of SVM: only the support vectors are consequential. The algorithm is efficient precisely because it ignores the vast majority of training points and focuses on the few that determine the boundary.

Mathematical Formulation

For readers interested in the mathematics, SVM optimises the following objective. Given training data {(x₁, y₁),…, (xₙ, yₙ)} where yᵢ ∈ {-1, +1}, the hard-margin SVM solves:

Here, w is the weight vector (perpendicular to the hyperplane), b is the bias term, and the constraint ensures that every point lies on the correct side of the margin. The term ||w||² controls the margin width: minimising it maximises the margin.

Soft Margin SVM and the C Parameter

Real-world data is rarely clean. Classes overlap, and outliers occur. The hard-margin SVM fails on any dataset that is not perfectly separable. The soft-margin SVM introduces slack variables ξᵢ that allow some points to violate the margin or even be misclassified:

The parameter C is the regularisation constant. A large C penalises misclassifications heavily (tight fit, risk of overfitting). A small C allows more misclassifications (smoother boundary, better generalisation). Tuning C is among the most important decisions in SVM usage.

The Kernel Trick

What if the data is not linearly separable in its original space, so that no hyperplane can divide the classes? The kernel trick is SVM’s principal mechanism for handling this case. It implicitly maps data into a higher-dimensional feature space in which a linear separator does exist, without ever computing coordinates in that space. Instead, every dot product x · x’ is replaced by a kernel function K(x, x’).

Common kernels include:

• Linear: K(x, x’) = x · x’, appropriate for linearly separable data.
• RBF (Gaussian): K(x, x’) = exp(-γ ||x – x’||²), the default choice for most nonlinear problems.
• Polynomial: K(x, x’) = (γ x · x’ + r)^d, used for polynomial decision boundaries.

The advantage of the kernel trick is computational. SVM optimisation requires only dot products between data points. Replacing those dot products with a kernel function produces the effect of operating in a high-dimensional (possibly infinite-dimensional) space without computing the explicit transformation. This is why SVM with an RBF kernel can handle strongly nonlinear boundaries at reasonable computational cost.

When to Use SVM

SVM performs particularly well in the following scenarios:

• Binary classification with labelled data: spam versus non-spam, tumour versus healthy, positive versus negative sentiment.
• High-dimensional data: text classification (TF-IDF vectors with thousands of features) and genomics data.
• Small to medium datasets: SVM’s training complexity of O(n²) to O(n³) makes it impractical for millions of samples, but it is highly effective on datasets in the thousands.
• When a clear margin is desired: the margin provides a geometric notion of confidence.
• When support vector interpretability matters: a practitioner can inspect which training examples serve as support vectors.

Strengths and Weaknesses

Strengths: Strong generalisation with appropriate tuning, effectiveness in high dimensions, memory efficiency (only support vectors are stored), robustness to overfitting when C is tuned, and versatility through different kernels.

Weaknesses: Limited scalability beyond roughly 100,000 samples, sensitivity to feature scaling, substantial dependence on kernel choice and hyperparameter settings, no direct provision of probability estimates (though Platt scaling can approximate them), and difficulty with highly noisy or strongly overlapping classes.

What Is OCSVM (One-Class SVM)?

The One-Class SVM, introduced by Bernhard Schölkopf and colleagues in 2001, inverts the standard SVM paradigm. Instead of learning a boundary between two classes, OCSVM learns a boundary around a single class. Points inside the boundary are treated as normal; points outside are treated as anomalous.

This formulation matches many real-world problems in which only one class is represented in the training data. Examples include:

• Millions of legitimate credit card transactions but only a handful of fraudulent ones.
• Years of sensor data from healthy machines but only a few recordings from moments preceding failure.
• Vast archives of normal network traffic but very few examples of novel attacks—and future attacks tend to differ from past ones.

In each of these cases, training a standard SVM is not feasible because representative examples of the negative class are unavailable. OCSVM addresses this constraint by requiring only normal data for training.

Visualising One-Class SVM

Unlike standard SVM, which requires two classes to construct a decision boundary, OCSVM requires only normal data. It learns the shape of the normal class and draws a tight boundary around it. Any new data point falling outside that boundary is flagged as anomalous.

Mathematical Formulation

Schölkopf’s formulation maps the data into a feature space via a kernel and then identifies a hyperplane that separates the data from the origin with maximum margin. The optimisation problem is:

Here ρ is the offset from the origin, and ν serves a dual role: it is an upper bound on the fraction of outliers and a lower bound on the fraction of support vectors. Setting ν = 0.05 means that at most 5% of the training data is expected to be outliers, and at least 5% of the points will serve as support vectors.

The ν Parameter

The ν (nu) parameter is the most important hyperparameter in OCSVM and warrants careful consideration:

• ν = 0.01: A very tight setting, permitting only 1% of training data outside the boundary. Appropriate when the training data is clean.
• ν = 0.05: A common starting point, allowing 5% as potential outliers.
• ν = 0.1: A more relaxed setting, useful when the training data is suspected to contain some contamination.
• ν = 0.5: A very loose setting under which up to half the data may fall outside the boundary. Rarely useful in practice.

The Effect of γ (Gamma) on the Boundary

When OCSVM is used with an RBF kernel (the most common configuration), the γ parameter controls how tightly the boundary wraps around the data. It is arguably the most sensitive parameter in the entire model:

The diagrams above illustrate the substantial effect of γ. At excessively low values, the boundary becomes so loose that it includes actual anomalies. At excessively high values, the boundary wraps so tightly that normal data is flagged as anomalous. Identifying an appropriate setting requires either domain knowledge of how tight the boundary should be or systematic evaluation against a validation set containing known anomalies.

When to Use OCSVM

• Anomaly or novelty detection: identifying unusual data points.
• Only normal data available: no labelled anomalies are present for training.
• Rare event detection: anomalies occur so infrequently that balanced classification is not feasible.
• Open-set recognition: the form of future anomalies is unknown.
• Manufacturing quality control: training on good parts, detecting defective ones.

Strengths and Weaknesses

Strengths: The method requires only normal data for training, naturally handles class imbalance, performs effectively in novelty detection (identifying anomaly types not previously observed), supports kernels for nonlinear boundaries, and provides a decision function score for ranking anomalies.

Weaknesses: The method shares the scalability constraints of SVM (O(n²) to O(n³)), is highly sensitive to the γ and ν parameters, offers no performance guarantee without labelled anomalies for validation, assumes that normal data is well clustered and anomalies are diffuse, and can struggle when the normal data exhibits multiple modes or clusters.

SVM and OCSVM: A Direct Comparison

The two algorithms are now placed side by side. The following diagram illustrates the fundamental difference in what each algorithm does:

Comprehensive Comparison Table

Implementation: Complete Python Code

Theory now gives way to practice. The following sections present complete, runnable Python scripts for both algorithms. Each script generates synthetic data, trains the model, visualises the results, and prints evaluation metrics.

SVM Implementation

import numpy as np
import matplotlib.pyplot as plt
from sklearn.svm import SVC
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split, GridSearchCV
from sklearn.preprocessing import StandardScaler
from sklearn.metrics import (
    classification_report, confusion_matrix, accuracy_score, f1_score
)

# --- Generate synthetic 2D data ---
X, y = make_classification(
    n_samples=300, n_features=2, n_redundant=0,
    n_informative=2, n_clusters_per_class=1,
    class_sep=1.2, random_state=42
)

# --- Split and scale ---
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42
)
scaler = StandardScaler()
X_train_s = scaler.fit_transform(X_train)
X_test_s = scaler.transform(X_test)

# --- Train SVM with RBF kernel ---
svm = SVC(kernel='rbf', C=1.0, gamma='scale', random_state=42)
svm.fit(X_train_s, y_train)

# --- Evaluate ---
y_pred = svm.predict(X_test_s)
print("=== SVM Results ===")
print(f"Accuracy: {accuracy_score(y_test, y_pred):.3f}")
print(f"F1 Score: {f1_score(y_test, y_pred):.3f}")
print(f"Support Vectors: {svm.n_support_}")
print("\nConfusion Matrix:")
print(confusion_matrix(y_test, y_pred))
print("\nClassification Report:")
print(classification_report(y_test, y_pred))

# --- Plot decision boundary ---
fig, ax = plt.subplots(1, 1, figsize=(8, 6))
xx, yy = np.meshgrid(
    np.linspace(X_train_s[:, 0].min()-1, X_train_s[:, 0].max()+1, 300),
    np.linspace(X_train_s[:, 1].min()-1, X_train_s[:, 1].max()+1, 300)
)
Z = svm.decision_function(np.c_[xx.ravel(), yy.ravel()]).reshape(xx.shape)

ax.contourf(xx, yy, Z, levels=np.linspace(Z.min(), Z.max(), 20),
            cmap='RdBu', alpha=0.3)
ax.contour(xx, yy, Z, levels=[-1, 0, 1],
           linestyles=['--', '-', '--'], colors='k')
ax.scatter(X_train_s[y_train==0, 0], X_train_s[y_train==0, 1],
           c='#3b82f6', label='Class 0', edgecolors='k', s=40)
ax.scatter(X_train_s[y_train==1, 0], X_train_s[y_train==1, 1],
           c='#ef4444', label='Class 1', edgecolors='k', s=40)
ax.scatter(svm.support_vectors_[:, 0], svm.support_vectors_[:, 1],
           s=120, facecolors='none', edgecolors='gold', linewidths=2,
           label='Support Vectors')
ax.set_title("SVM Decision Boundary (RBF Kernel)")
ax.legend()
plt.tight_layout()
plt.savefig("svm_decision_boundary.png", dpi=150)
plt.show()

# --- Hyperparameter tuning ---
param_grid = {
    'C': [0.1, 1, 10, 100],
    'gamma': ['scale', 'auto', 0.01, 0.1, 1],
    'kernel': ['rbf', 'poly']
}
grid = GridSearchCV(SVC(), param_grid, cv=5, scoring='f1', n_jobs=-1)
grid.fit(X_train_s, y_train)
print(f"\nBest params: {grid.best_params_}")
print(f"Best CV F1:  {grid.best_score_:.3f}")

OCSVM Implementation

import numpy as np
import matplotlib.pyplot as plt
from sklearn.svm import OneClassSVM
from sklearn.preprocessing import StandardScaler
from sklearn.metrics import classification_report, f1_score, precision_score, recall_score

# --- Generate synthetic normal data + anomalies ---
np.random.seed(42)
n_normal = 300
n_anomaly = 30

# Normal data: two Gaussian clusters
normal_data = np.vstack([
    np.random.randn(n_normal // 2, 2) * 0.5 + [2, 2],
    np.random.randn(n_normal // 2, 2) * 0.5 + [3, 3],
])

# Anomalies: scattered uniformly in a wider region
anomalies = np.random.uniform(low=-2, high=7, size=(n_anomaly, 2))

# Labels: +1 = normal, -1 = anomaly (OCSVM convention)
y_normal = np.ones(n_normal)
y_anomaly = -np.ones(n_anomaly)

# --- Scale features (critical for SVM-based methods!) ---
scaler = StandardScaler()
normal_scaled = scaler.fit_transform(normal_data)

# --- Train OCSVM on normal data only ---
ocsvm = OneClassSVM(kernel='rbf', gamma=0.3, nu=0.05)
ocsvm.fit(normal_scaled)

# --- Evaluate on combined dataset ---
X_all = np.vstack([normal_data, anomalies])
X_all_scaled = scaler.transform(X_all)
y_true = np.concatenate([y_normal, y_anomaly])

y_pred = ocsvm.predict(X_all_scaled)
scores = ocsvm.decision_function(X_all_scaled)

print("=== OCSVM Results ===")
print(f"Precision: {precision_score(y_true, y_pred, pos_label=-1):.3f}")
print(f"Recall:    {recall_score(y_true, y_pred, pos_label=-1):.3f}")
print(f"F1 Score:  {f1_score(y_true, y_pred, pos_label=-1):.3f}")
print(f"Support Vectors: {ocsvm.support_vectors_.shape[0]}")
print("\nClassification Report:")
print(classification_report(y_true, y_pred,
                            target_names=['Anomaly (-1)', 'Normal (+1)']))

# --- Plot decision boundary ---
fig, ax = plt.subplots(1, 1, figsize=(8, 6))
xx, yy = np.meshgrid(
    np.linspace(X_all_scaled[:, 0].min()-1, X_all_scaled[:, 0].max()+1, 300),
    np.linspace(X_all_scaled[:, 1].min()-1, X_all_scaled[:, 1].max()+1, 300)
)
Z = ocsvm.decision_function(np.c_[xx.ravel(), yy.ravel()]).reshape(xx.shape)

ax.contourf(xx, yy, Z, levels=np.linspace(Z.min(), 0, 10),
            cmap='Reds_r', alpha=0.3)
ax.contourf(xx, yy, Z, levels=np.linspace(0, Z.max(), 10),
            cmap='Greens', alpha=0.3)
ax.contour(xx, yy, Z, levels=[0], linewidths=2, colors='black')

ax.scatter(normal_scaled[:, 0], normal_scaled[:, 1],
           c='#10b981', s=30, label='Normal', edgecolors='k', linewidths=0.5)
anomalies_scaled = scaler.transform(anomalies)
ax.scatter(anomalies_scaled[:, 0], anomalies_scaled[:, 1],
           c='#ef4444', s=60, marker='D', label='Anomaly', edgecolors='k')
ax.set_title("OCSVM Decision Boundary")
ax.legend()
plt.tight_layout()
plt.savefig("ocsvm_decision_boundary.png", dpi=150)
plt.show()

# --- Tune nu and gamma ---
best_f1 = 0
best_params = {}
for nu in [0.01, 0.03, 0.05, 0.1, 0.2]:
    for gamma in [0.01, 0.05, 0.1, 0.3, 0.5, 1.0]:
        model = OneClassSVM(kernel='rbf', gamma=gamma, nu=nu)
        model.fit(normal_scaled)
        preds = model.predict(X_all_scaled)
        f1 = f1_score(y_true, preds, pos_label=-1)
        if f1 > best_f1:
            best_f1 = f1
            best_params = {'nu': nu, 'gamma': gamma}

print(f"\nBest params: {best_params}")
print(f"Best F1:     {best_f1:.3f}")

Side-by-Side Comparison Script

import numpy as np
import matplotlib.pyplot as plt
from sklearn.svm import SVC, OneClassSVM
from sklearn.preprocessing import StandardScaler
from sklearn.metrics import f1_score, accuracy_score

np.random.seed(42)

# Generate data: normal class + rare anomaly class
n_normal, n_anomaly = 400, 20
X_normal = np.random.randn(n_normal, 2) * 0.8 + [3, 3]
X_anomaly = np.random.uniform(0, 6, size=(n_anomaly, 2))

X_all = np.vstack([X_normal, X_anomaly])
y_all = np.array([1]*n_normal + [-1]*n_anomaly)

scaler = StandardScaler()
X_scaled = scaler.fit_transform(X_all)
X_normal_scaled = scaler.transform(X_normal)

# --- Approach 1: SVM (supervised — uses BOTH labels) ---
svm = SVC(kernel='rbf', C=10, gamma='scale')
svm.fit(X_scaled, y_all)
y_pred_svm = svm.predict(X_scaled)

# --- Approach 2: OCSVM (semi-supervised — trained on normal only) ---
ocsvm = OneClassSVM(kernel='rbf', gamma=0.3, nu=0.05)
ocsvm.fit(X_normal_scaled)
y_pred_ocsvm = ocsvm.predict(X_scaled)

# --- Compare metrics ---
print("=" * 50)
print(f"{'Metric':<25} {'SVM':>10} {'OCSVM':>10}")
print("=" * 50)
print(f"{'Accuracy':<25} {accuracy_score(y_all, y_pred_svm):>10.3f} "
      f"{accuracy_score(y_all, y_pred_ocsvm):>10.3f}")
print(f"{'F1 (anomaly class)':<25} {f1_score(y_all, y_pred_svm, pos_label=-1):>10.3f} "
      f"{f1_score(y_all, y_pred_ocsvm, pos_label=-1):>10.3f}")
print(f"{'F1 (normal class)':<25} {f1_score(y_all, y_pred_svm, pos_label=1):>10.3f} "
      f"{f1_score(y_all, y_pred_ocsvm, pos_label=1):>10.3f}")
print("=" * 50)

# --- Plot both ---
fig, axes = plt.subplots(1, 2, figsize=(14, 6))
for ax, model, title, preds in zip(
    axes, [svm, ocsvm],
    ["SVM (supervised)", "OCSVM (normal-only training)"],
    [y_pred_svm, y_pred_ocsvm]
):
    xx, yy = np.meshgrid(
        np.linspace(X_scaled[:,0].min()-1, X_scaled[:,0].max()+1, 200),
        np.linspace(X_scaled[:,1].min()-1, X_scaled[:,1].max()+1, 200)
    )
    Z = model.decision_function(
        np.c_[xx.ravel(), yy.ravel()]
    ).reshape(xx.shape)
    ax.contour(xx, yy, Z, levels=[0], colors='k', linewidths=2)
    ax.contourf(xx, yy, Z, levels=np.linspace(Z.min(), Z.max(), 20),
                cmap='RdYlGn', alpha=0.3)
    ax.scatter(X_scaled[y_all==1, 0], X_scaled[y_all==1, 1],
               c='#10b981', s=20, label='Normal')
    ax.scatter(X_scaled[y_all==-1, 0], X_scaled[y_all==-1, 1],
               c='#ef4444', s=60, marker='D', label='Anomaly')
    ax.set_title(title)
    ax.legend(loc='lower right')

plt.suptitle("SVM vs OCSVM on the Same Dataset", fontsize=14, y=1.02)
plt.tight_layout()
plt.savefig("svm_vs_ocsvm_comparison.png", dpi=150, bbox_inches='tight')
plt.show()

Real-World Use Cases

SVM Use Cases

Standard SVM has served as a reliable instrument for classification tasks for more than two decades. The following are among its most consequential applications:

OCSVM Use Cases

OCSVM is particularly well suited to problems in which anomalies are rare, undefined, or continually evolving:

Practical Decision Guide: When to Use Which

The decision between SVM and OCSVM for a new problem can be approached through the following sequence of questions:

Question 1: Are labelled examples available from both classes?

• Yes → Consider SVM. The data permits training of a supervised classifier.
• No → Use OCSVM. Learning is possible only from the available class.

Question 2: Is one class extremely rare (less than 1% of the data)?

• Yes → OCSVM is likely the better choice. Even when some labelled anomalies are available, the extreme imbalance degrades SVM performance unless heavy resampling is applied.
• No → SVM with appropriate class weighting should perform well.

Question 3: Is the objective classification or anomaly detection?

• Classification (assigning examples to known categories) → SVM.
• Anomaly detection (identifying examples that do not belong) → OCSVM.

Question 4: Does the abnormal class have a clear, stable definition?

• Yes (for example, spam exhibits consistent patterns) → SVM can learn these patterns.
• No (for example, novel attacks or unprecedented failures) → OCSVM, since it does not require explicit knowledge of how anomalies appear.

Scenario Recommendations

Advanced Topics

SVDD: Support Vector Data Description

SVDD, proposed by Tax and Duin (2004), is closely related to OCSVM. Where OCSVM identifies a hyperplane in feature space that separates the data from the origin, SVDD identifies the minimum enclosing hypersphere that contains most of the data. Points outside the sphere are anomalies.

In practice, SVDD with an RBF kernel produces results identical to those of OCSVM (the two are mathematically equivalent under Gaussian kernels). The principal difference is conceptual: SVDD frames the problem in terms of spheres, while OCSVM frames it in terms of hyperplanes. Most practitioners use OCSVM via scikit-learn because of its wider availability.

Multi-Class SVM

Standard SVM is inherently binary, but two strategies extend it to multi-class problems:

• One-vs-Rest (OvR): Train K binary classifiers, each separating one class from all others. Assign the class with the highest decision function value. K classifiers are required.
• One-vs-One (OvO): Train K(K-1)/2 binary classifiers, one for each pair of classes, and use majority voting. This is the default for scikit-learn’s SVC and often performs better in practice, though more models must be trained.

Deep SVDD: Neural Networks and OCSVM

Deep SVDD (Ruff et al., 2018) replaces the kernel trick with a deep neural network. Instead of mapping data to a kernel-defined feature space and identifying a hypersphere, it trains a neural network to map data into a learned representation space in which normal data clusters tightly around a centre point. The loss function minimises the distance from the centre of normal data representations.

This approach scales considerably better than kernel-based OCSVM and can handle high-dimensional data such as images and time series. Libraries such as PyOD provide Deep SVDD as a default option.

OCSVM Alternatives: Isolation Forest and LOF

OCSVM for Time-Series Anomaly Detection

OCSVM does not natively handle time-series data, but with appropriate feature engineering it becomes an effective time-series anomaly detector. The standard procedure is as follows:

1. Sliding window: Convert the time series into fixed-length windows (for example, 60-second windows).
2. Feature extraction: For each window, compute statistical features—mean, standard deviation, minimum, maximum, skewness, kurtosis, spectral features, and rolling statistics.
3. Train OCSVM: Fit on feature vectors drawn from known-normal periods.
4. Detect: Score new windows; those below the decision threshold are flagged as anomalies.

# Time-series anomaly detection with OCSVM
import numpy as np
from sklearn.svm import OneClassSVM
from sklearn.preprocessing import StandardScaler

def extract_features(window):
    """Extract statistical features from a time-series window."""
    return [
        np.mean(window), np.std(window),
        np.min(window), np.max(window),
        np.percentile(window, 25), np.percentile(window, 75),
        np.max(window) - np.min(window),  # range
        np.mean(np.abs(np.diff(window))),  # mean abs change
    ]

# Simulate normal time series + anomaly
np.random.seed(42)
normal_ts = np.sin(np.linspace(0, 20*np.pi, 2000)) + np.random.randn(2000)*0.1
anomaly_ts = np.sin(np.linspace(0, 2*np.pi, 100)) + np.random.randn(100)*0.5 + 3

# Sliding window feature extraction
window_size = 50
stride = 10
features_normal = [
    extract_features(normal_ts[i:i+window_size])
    for i in range(0, len(normal_ts)-window_size, stride)
]
features_anomaly = [
    extract_features(anomaly_ts[i:i+window_size])
    for i in range(0, len(anomaly_ts)-window_size, stride)
]

X_normal = np.array(features_normal)
X_anomaly = np.array(features_anomaly)

scaler = StandardScaler()
X_normal_s = scaler.fit_transform(X_normal)
X_anomaly_s = scaler.transform(X_anomaly)

ocsvm = OneClassSVM(kernel='rbf', gamma=0.1, nu=0.05)
ocsvm.fit(X_normal_s)

print(f"Normal windows flagged as anomaly: "
      f"{(ocsvm.predict(X_normal_s) == -1).sum()}/{len(X_normal_s)}")
print(f"Anomaly windows detected: "
      f"{(ocsvm.predict(X_anomaly_s) == -1).sum()}/{len(X_anomaly_s)}")

Performance Comparison

How do these methods compare on standard anomaly detection benchmarks? The following table summarises typical performance across commonly used datasets. Exact figures vary with preprocessing and hyperparameter choices, but the relative rankings are consistent across studies:

Key observations:

• Supervised SVM consistently outperforms all unsupervised methods, but it requires labelled anomalies, which are often unavailable.
• OCSVM performs competitively with Isolation Forest on most benchmarks, with the additional advantage of producing a smooth decision boundary.
• Isolation Forest is typically the first choice for large datasets owing to its O(n log n) complexity.
• OCSVM is particularly effective when the normal data has a clear, compact structure in feature space.

Computational Complexity and Scalability

Both SVM and OCSVM have a training complexity of O(n²) to O(n³), where n denotes the number of training samples. This arises from solving a quadratic programming problem. In practice:

• Up to 10,000 samples: Both train in seconds to minutes without concern.
• 10,000 to 50,000 samples: Training takes minutes to an hour, and remains feasible.
• 50,000 to 100,000 samples: Training may take hours. Subsampling or approximate methods should be considered.
• Above 100,000 samples: Direct application is impractical without workarounds.

Hyperparameter Tuning Guide

Appropriate hyperparameter settings often determine whether a model works at all. The following provides a complete tuning guide:

Tuning SVM

Use GridSearchCV or RandomizedSearchCV with 5-fold cross-validation. The appropriate metric depends on the problem: accuracy for balanced classes, F1 for imbalanced classes, and AUC-ROC when threshold-independent evaluation is desired.

Tuning OCSVM

Grid Search and Random Search

For SVM with three parameters (C, γ, kernel), a full grid search over the ranges above requires evaluating over 100 combinations per CV fold. Random search (Bergstra and Bengio, 2012) often finds good hyperparameters more quickly by sampling random combinations, particularly when certain parameters matter more than others. In this setting, γ almost always carries more weight than the remaining parameters.

from sklearn.model_selection import RandomizedSearchCV
from scipy.stats import loguniform

param_dist = {
    'C': loguniform(0.01, 1000),
    'gamma': loguniform(0.001, 10),
    'kernel': ['rbf', 'poly'],
}
random_search = RandomizedSearchCV(
    SVC(), param_dist, n_iter=50, cv=5,
    scoring='f1', random_state=42, n_jobs=-1
)
random_search.fit(X_train_scaled, y_train)
print(f"Best: {random_search.best_params_} → F1={random_search.best_score_:.3f}")

Common Pitfalls

The following mistakes recur frequently among practitioners using these algorithms:

Using SVM Without Labelled Anomalies

The mistake is straightforward in principle but common in practice. A team aims to detect anomalies, selects SVM out of familiarity, and then either fabricates anomaly labels or uses the few available anomalies as a tiny minority class. The resulting model performs poorly because SVM requires representative examples from both classes. When labelled anomalies are unavailable—and in most anomaly detection problems they are not—OCSVM should be used instead.

Setting ν Too Low or Too High

Setting ν = 0.001 when the training data contains 5% contamination causes the model to enclose everything, including real anomalies, within the normal boundary. Setting ν = 0.5 produces a boundary so loose that half of the normal data is flagged. The value of ν should match the best available estimate of contamination, and when uncertain, a moderately higher value (0.05 is a safe default) should be preferred.

Failing to Scale Features

This is the most common mistake encountered with SVM and OCSVM. Both algorithms are based on distances (through their kernels), and features of larger magnitude will dominate. Features should always be standardised (zero mean, unit variance) before training. Use StandardScaler and fit it on training data only:

# CORRECT: fit on training data, transform both
scaler = StandardScaler()
X_train_s = scaler.fit_transform(X_train)
X_test_s = scaler.transform(X_test)  # use training statistics!

# WRONG: fitting scaler on test data leaks information
# scaler.fit_transform(X_test)  # NEVER do this

Using a Linear Kernel on Nonlinear Data

A linear kernel produces a hyperplane decision boundary. If the classes are arranged in concentric circles, spirals, or any other nonlinear pattern, a linear kernel will fail outright. When in doubt, RBF is the preferred starting point: it can approximate linear boundaries with appropriate γ, so little is lost by defaulting to it.

Failing to Tune γ

The γ parameter for the RBF kernel is arguably the most important and most sensitive hyperparameter in both SVM and OCSVM. The default (‘scale’ in scikit-learn) is reasonable but rarely optimal. γ should always be included in the hyperparameter search. Small changes in γ can produce substantial changes in model behaviour; the difference between a working model and an ineffective one can amount to a factor of two in γ.

Training OCSVM on Contaminated Data

OCSVM assumes that its training data is “normal.” When anomalies enter the training set, which occurs frequently in practice, the model learns an overly permissive boundary that incorporates those anomalies as normal. Mitigation strategies include careful curation of training data, use of a small ν that allows some contamination, and pre-filtering of obvious outliers before training.

Putting It Together

SVM and OCSVM share a name, a mathematical foundation, and a kernel-based approach to learning, but they address fundamentally different problems. SVM is a supervised classifier that requires labelled examples from both classes to draw a separating boundary between them. OCSVM is a semi-supervised anomaly detector that requires only normal data to draw a boundary around the normal class.

The choice between them is not a matter of which is preferable in general, but of which matches the problem:

• Labelled data from both classes is available. SVM will almost always outperform OCSVM, since it uses more information.
• Only normal data is available, or anomalies are too rare and diverse to label. OCSVM is the appropriate tool. It builds a model of normality and detects anything unusual, including anomaly types not previously observed.
• Scaling to millions of samples is required. Consider Isolation Forest or SGD-based variants in place of kernel SVM or OCSVM.

Several essential practices apply throughout: scale features, tune γ and C (or ν), start with an RBF kernel unless a specific reason argues otherwise, and validate the model as rigorously as the labelled data permits. With these principles in place, the appropriate SVM variant can be selected for any classification or anomaly detection problem.

When the distinction between SVM and OCSVM is conflated, the basis for distinguishing them—and the circumstances in which each is appropriate—should now be clear.

References

1. Vapnik, V. (1995). The Nature of Statistical Learning Theory. Springer-Verlag.
2. Schölkopf, B., Platt, J., Shawe-Taylor, J., Smola, A., & Williamson, R. (2001). “Estimating the Support of a High-Dimensional Distribution.” Neural Computation, 13(7), 1443-1471.
3. Tax, D. M. J., & Duin, R. P. W. (2004). “Support Vector Data Description.” Machine Learning, 54(1), 45-66.
4. Ruff, L., et al. (2018). “Deep One-Class Classification.” Proceedings of the 35th International Conference on Machine Learning (ICML).
5. Bergstra, J., & Bengio, Y. (2012). “Random Search for Hyper-Parameter Optimization.” Journal of Machine Learning Research, 13, 281-305.
6. Pedregosa, F., et al. (2011). “Scikit-learn: Machine Learning in Python.” Journal of Machine Learning Research, 12, 2825-2830.
7. Liu, F. T., Ting, K. M., & Zhou, Z.-H. (2008). “Isolation Forest.” Proceedings of the 8th IEEE International Conference on Data Mining.
8. Breunig, M. M., Kriegel, H.-P., Ng, R. T., & Sander, J. (2000). “LOF: Identifying Density-Based Local Outliers.” Proceedings of the 2000 ACM SIGMOD.
9. scikit-learn documentation: Support Vector Machines.
10. scikit-learn documentation: Novelty and Outlier Detection.

Consider an exceptionally capable assistant able to analyse data, write code and answer complex questions, but confined to a windowless room with no telephone, no internet connection and no access to any of the user’s files. Each time the user requires the assistant to check email, the user must print the messages, deliver them to the room, slide them under the door, wait for a response, and then carry the reply back. Multiplying this process across every tool in use, including calendar, database, project management system and cloud infrastructure, describes the state of AI integrations before the Model Context Protocol. The arrangement is as inefficient as it sounds.

Before MCP, every AI application had to build a custom integration for every data source and tool it sought to access. Allowing Claude to read Google Drive required a custom integration. Permitting database queries required another. Connecting to Slack required a further one. Every AI company and every tool vendor had to negotiate, build and maintain a unique connector. The arithmetic was unforgiving: N AI applications multiplied by M tools produced N times M custom integrations, each with its own authentication flow, data format and failure modes.

The situation resembled the early internet before HTTP. Each system used its own method of transferring documents between computers, and none communicated with the others. HTTP then introduced a single standard for requesting and serving documents, and the web expanded rapidly.

MCP performs the same function for AI. Announced by Anthropic in late 2024 and open-sourced from the outset, the Model Context Protocol is a universal standard that allows any AI model to connect to any tool or data source through a single, well-defined protocol. An MCP server constructed once can immediately be used by any MCP-compatible AI application, including Claude Desktop, Claude Code, VS Code Copilot, Cursor, Windsurf and Zed. No custom integrations are required and no vendor lock-in is introduced.

The remainder of this article presents a comprehensive examination of MCP. It explains the architecture, the three core primitives and the operation of the transport layer, and walks through the construction of MCP servers in both Python and TypeScript.

What Is MCP?

The Model Context Protocol (MCP) is an open standard for communication between AI applications, referred to as clients or hosts, and external data sources and tools, referred to as servers. It functions as a universal language that AI models and tools can use to understand one another, regardless of which entity built them.

The USB Analogy

The clearest way to understand MCP is through an analogy with USB. Before USB, every peripheral, including printers, scanners, keyboards and cameras, used its own proprietary cable and connector. Each desk became a tangle of incompatible cables, and purchasing a new device required confirming that the correct port was supported. USB introduced a single connector and a single protocol covering every device. USB-C extended this further by carrying charging, data, video and audio over a single cable across laptops, phones, tablets and monitors.

MCP is the USB-C of AI integrations. A single standard connector serves every purpose. A GitHub MCP server functions with Claude, with Cursor, with VS Code Copilot and with any future AI application that implements the MCP client specification. The server is built once and used in every context.

Who Created It and Why

MCP was created by Anthropic and open-sourced under a permissive licence. The specification, SDKs and reference implementations are publicly available on GitHub. Anthropic did not develop MCP in order to lock developers into Claude. The protocol was developed because the N times M integration problem was constraining the entire AI industry.

The arithmetic is straightforward. Suppose there are 10 AI applications and 50 tools. Without a standard protocol, 10 multiplied by 50 produces 500 custom integrations. Each integration must be built, tested, documented and maintained. Adding one further AI application then requires 50 additional integrations, and adding one further tool requires 10 additional integrations. The problem scales poorly.

With MCP, each AI application implements a single MCP client, and each tool implements a single MCP server. The total becomes 10 plus 50, or 60 implementations. Adding a new AI application requires one further client. Adding a new tool requires one further server. The problem becomes linear rather than multiplicative.

What MCP Is Not

To avoid confusion, the following clarifications regarding what MCP is not are useful.

• MCP is not an API. It is a protocol specification, in the same category as HTTP or WebSocket. APIs are constructed on top of protocols.
• MCP is not a framework. It is not LangChain, CrewAI or AutoGen. Frameworks provide opinionated structures for building applications. MCP provides a communication standard.
• MCP is not a library. Although SDKs exist for Python and TypeScript, the protocol itself is language-agnostic. It can be implemented in Rust, Go, Java or any language capable of handling JSON-RPC.
• MCP is not Anthropic-only. It is an open standard. Microsoft, Google and many open-source projects are adopting it.

The closest analogy in software engineering is the Language Server Protocol (LSP), developed by Microsoft for VS Code. LSP standardised how code editors communicate with language-specific intelligence servers responsible for autocomplete, go-to-definition and error checking. Before LSP, every editor required a dedicated plugin for every language. After LSP, a single language server functions with any editor. MCP performs the same role for AI models connecting to tools and data.

Current Adoption

As of early 2026, MCP has been adopted by a rapidly growing set of applications and platforms.

The Architecture of MCP

MCP follows a client-server architecture composed of three distinct components. Understanding how these components fit together is essential before examining the primitives and transport layers in detail.

Three Core Components

The architecture is structured as follows.

┌─────────────────────────────────────────────────────┐
│                    MCP HOST                          │
│              (e.g., Claude Desktop)                  │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ MCP      │  │ MCP      │  │ MCP      │          │
│  │ Client 1 │  │ Client 2 │  │ Client 3 │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
└───────┼──────────────┼──────────────┼────────────────┘
        │              │              │
        ▼              ▼              ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ MCP      │  │ MCP      │  │ MCP      │
  │ Server A │  │ Server B │  │ Server C │
  │ (GitHub) │  │ (DB)     │  │ (Slack)  │
  └────┬─────┘  └────┬─────┘  └────┬─────┘
       │              │              │
       ▼              ▼              ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │ GitHub   │  │ PostgreSQL│  │ Slack    │
  │ API      │  │ Database │  │ API      │
  └──────────┘  └──────────┘  └──────────┘

MCP Hosts are the AI applications that require access to external tools and data. Claude Desktop, Claude Code, Cursor and any custom AI application a developer may build can serve as an MCP host. The host is responsible for managing the user interface, running the AI model, and coordinating connections to one or more MCP servers. In the HTTP analogy, the host corresponds to a web browser: it is the application with which the user interacts, and it knows how to speak the protocol to complete tasks.

MCP Clients are protocol-level connectors that reside within hosts. Each client maintains a one-to-one connection with a specific MCP server. A Claude Desktop installation connected to three MCP servers (GitHub, a database and Slack) runs three MCP clients internally. The client handles low-level communication, including sending JSON-RPC messages, negotiating capabilities and managing the connection lifecycle. Developers typically do not build clients directly, since the host application provides them.

MCP Servers are the services that expose tools, resources and prompts to AI applications. A GitHub MCP server may expose tools such as create_issue, search_repos and list_pull_requests. A database MCP server may expose tools such as run_query and list_tables. Each server exposes its capabilities through a standard interface, and any MCP client can discover and use them. In the HTTP analogy, MCP servers correspond to web servers: they serve content and functionality to any client capable of speaking the protocol.

MCP servers may run locally on a developer’s machine using the stdio transport, in which case they operate as a subprocess, or remotely as a web service using the HTTP+SSE transport. This flexibility means that a developer can begin with a simple local server for personal use and later deploy it as a shared service for an entire team.

How It Differs from Traditional API Integrations

In a traditional integration, the AI application calls an external API directly. The developer writes HTTP requests, handles authentication, parses responses and manages errors, all in custom code embedded in the application. When the API changes, the developer updates the code. When a new AI application must be supported, the integration is rewritten.

With MCP, an abstraction layer sits between the application and the underlying service. The AI application neither knows nor needs to know how the MCP server communicates with GitHub, Slack or a particular database. It is only required to speak MCP. The server handles all API-specific logic. The implications of this separation of concerns are as follows.

• AI applications can support new tools without code changes, since the host need only be pointed at a new MCP server.
• Tool providers can update their APIs without disrupting AI integrations, since only the MCP server requires modification.
• The AI model can discover available tools dynamically at runtime through the standard capability-negotiation mechanism.

The Three Primitives: Tools, Resources, and Prompts

MCP defines three core primitives, that is, three categories of capability that servers may expose to clients. Each serves a different purpose and is controlled by a different party. Understanding these primitives is essential to understanding MCP.

Tools (Model-Controlled)

Tools are functions that the AI model can invoke to perform actions. They are the most commonly used primitive and the first that practitioners associate with MCP. Tools allow the model to search files, run database queries, send messages, create GitHub issues, deploy code and perform any other operation that can be expressed as a function call.

Each tool is defined by a name, a description (which the model reads to determine when the tool should be used) and an input schema in JSON Schema format. When the model determines that a tool is required in order to answer the user’s question, it generates the appropriate arguments, the MCP client sends the call to the server, the server executes the function, and the result returns to the model.

A complete example of a tool definition is shown below.

{
  "name": "query_database",
  "description": "Execute a read-only SQL query against the application database. Use this tool when the user asks about data stored in our systems — customer counts, order history, revenue figures, etc. Only SELECT queries are allowed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The SQL SELECT query to execute"
      },
      "database": {
        "type": "string",
        "enum": ["production", "analytics", "staging"],
        "description": "Which database to query"
      },
      "limit": {
        "type": "integer",
        "default": 100,
        "description": "Maximum number of rows to return"
      }
    },
    "required": ["query", "database"]
  }
}

The central point to understand is that tools are model-controlled. The AI model determines when to invoke a tool based on the user’s intent. When the user asks “how many customers signed up last month?”, the model determines that it must call query_database in order to answer. The model generates the SQL, selects the database and issues the call. The concept is the same as function calling or tool calling in the Claude and OpenAI APIs, but standardised across all MCP-compatible applications.

Resources (Application-Controlled)

Resources are data that the application can expose to the AI model. If tools resemble POST endpoints in REST in that they perform actions, resources resemble GET endpoints in that they supply data. Resources provide the model with context, including background information, file contents, configuration and documentation, that helps it understand the user’s situation and generate higher-quality responses.

Resources are identified by URIs in the same manner as web pages. A file system MCP server might expose resources such as file:///home/user/project/README.md. A database server might expose db://users/123 to represent a specific user record. A project management server might expose jira://PROJECT-456 for a specific ticket.

An example of a resource definition is shown below.

{
  "uri": "docs://api/authentication",
  "name": "Authentication API Documentation",
  "description": "Complete documentation for the authentication API, including endpoints, request/response formats, and error codes",
  "mimeType": "text/markdown"
}

Resources are application-controlled rather than model-controlled. The host application determines when to fetch and present resources to the model. When a user opens a project in Claude Code, for example, the application may automatically fetch the project’s README and configuration files as resources, supplying the model with context before any question is asked. Resources can also be dynamic, since a server may support subscriptions that notify the client when a resource changes.

Prompts (User-Controlled)

Prompts are pre-built prompt templates that servers may expose. They provide users, or applications, with rapid access to common workflows without requiring the full instructions to be typed each time. A code review MCP server might expose a /review-code prompt containing a detailed template for analysing code quality, security and performance. A documentation server might expose a /summarize prompt optimised for generating concise summaries.

An example of a prompt definition is shown below.

{
  "name": "review-code",
  "description": "Perform a thorough code review with focus on bugs, security, performance, and maintainability",
  "arguments": [
    {
      "name": "code",
      "description": "The code to review",
      "required": true
    },
    {
      "name": "language",
      "description": "Programming language of the code",
      "required": false
    },
    {
      "name": "focus",
      "description": "Specific area to focus on (security, performance, readability)",
      "required": false
    }
  ]
}

Prompts are user-controlled. The user explicitly selects a prompt from the available list, supplies any required arguments, and the expanded prompt is sent to the model. This differs from tools, where the model decides, and from resources, where the application decides.

Comparison Table

Transport Layer: How MCP Communicates

The protocol requires a mechanism for transmitting messages between clients and servers. MCP supports two transport mechanisms, each suited to different deployment scenarios.

stdio (Standard I/O) Transport

The stdio transport is the simplest and most common way to run MCP servers. The host application launches the MCP server as a subprocess on the same machine, and the two communicate via standard input (stdin) and standard output (stdout). Messages are JSON-RPC 2.0 objects, sent as newline-delimited JSON.

The sequence of events when a stdio MCP server is configured in Claude Desktop is as follows.

1. The server configuration is added to claude_desktop_config.json.
2. Claude Desktop launches the server process, for example python weather_server.py.
3. The client sends an initialize request over stdin.
4. The server responds with its capabilities, including the tools, resources and prompts it offers.
5. The client sends a tools/list request to discover available tools.
6. When the model wishes to invoke a tool, the client sends a tools/call request over stdin.
7. The server executes the tool and returns the result over stdout.

The stdio transport is well suited to local development, personal tools and single-user scenarios. It requires no network configuration, no authentication setup and no supporting infrastructure. Only the server script on the local machine is required.

HTTP + Server-Sent Events (SSE) Transport

For remote servers, shared team tools and production deployments, MCP supports HTTP with Server-Sent Events. The client connects to the server over HTTP, sends requests as HTTP POST messages, and receives responses and notifications via an SSE stream.

This transport enables scenarios that stdio cannot accommodate.

• Remote access: the server runs on a different machine, in the cloud, or behind a load balancer.
• Multi-user operation: multiple clients may connect to the same server simultaneously.
• Authentication: standard HTTP authentication mechanisms, including Bearer tokens and OAuth, may be used.
• Monitoring: standard HTTP logging, metrics and tracing tools function by default.
• Scalability: the server can be deployed as a containerised service with horizontal scaling.

Transport Comparison

Building a First MCP Server: A Complete Tutorial

Theory is useful, but practical construction provides a clearer understanding. This section walks through two complete, runnable MCP servers, one in Python and one in TypeScript. Both are fully functional and ready to connect to Claude Desktop or Claude Code.

Python MCP Server: Weather Service

Step 1: Install dependencies

# Create a new project directory
mkdir mcp-weather-server && cd mcp-weather-server

# Initialize with uv (recommended) or pip
uv init
uv add mcp httpx

# Or with pip
pip install mcp httpx

Step 2: Create the server

Create a file called weather_server.py:

"""MCP Weather Server — exposes weather tools, resources, and prompts."""

import json
import httpx
from mcp.server.fastmcp import FastMCP

# Create the MCP server
mcp = FastMCP("weather-service")

# --- TOOLS (Model-Controlled) ---

@mcp.tool()
async def get_weather(city: str, units: str = "celsius") -> str:
    """Get the current weather for a city.

    Use this tool when the user asks about weather conditions,
    temperature, or forecasts for a specific location.

    Args:
        city: The city name (e.g., "Tokyo", "New York", "London")
        units: Temperature units — "celsius" or "fahrenheit"
    """
    # Using the free Open-Meteo API (no API key required)
    # First, geocode the city name
    async with httpx.AsyncClient() as client:
        geo_response = await client.get(
            "https://geocoding-api.open-meteo.com/v1/search",
            params={"name": city, "count": 1}
        )
        geo_data = geo_response.json()

        if "results" not in geo_data:
            return f"Could not find location: {city}"

        location = geo_data["results"][0]
        lat = location["latitude"]
        lon = location["longitude"]
        name = location["name"]
        country = location.get("country", "")

        # Fetch weather data
        temp_unit = "fahrenheit" if units == "fahrenheit" else "celsius"
        weather_response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": lat,
                "longitude": lon,
                "current": "temperature_2m,wind_speed_10m,relative_humidity_2m,weather_code",
                "temperature_unit": temp_unit,
            }
        )
        weather = weather_response.json()["current"]

        unit_symbol = "°F" if units == "fahrenheit" else "°C"
        return (
            f"Weather in {name}, {country}:\n"
            f"Temperature: {weather['temperature_2m']}{unit_symbol}\n"
            f"Humidity: {weather['relative_humidity_2m']}%\n"
            f"Wind Speed: {weather['wind_speed_10m']} km/h\n"
            f"Conditions: Weather code {weather['weather_code']}"
        )


@mcp.tool()
async def get_forecast(city: str, days: int = 3) -> str:
    """Get a multi-day weather forecast for a city.

    Args:
        city: The city name
        days: Number of days to forecast (1-7)
    """
    days = min(max(days, 1), 7)

    async with httpx.AsyncClient() as client:
        geo_response = await client.get(
            "https://geocoding-api.open-meteo.com/v1/search",
            params={"name": city, "count": 1}
        )
        geo_data = geo_response.json()

        if "results" not in geo_data:
            return f"Could not find location: {city}"

        location = geo_data["results"][0]
        weather_response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": location["latitude"],
                "longitude": location["longitude"],
                "daily": "temperature_2m_max,temperature_2m_min,weather_code",
                "forecast_days": days,
            }
        )
        daily = weather_response.json()["daily"]

        lines = [f"Forecast for {location['name']}:"]
        for i in range(days):
            lines.append(
                f"  {daily['time'][i]}: "
                f"{daily['temperature_2m_min'][i]}°C — "
                f"{daily['temperature_2m_max'][i]}°C "
                f"(code: {daily['weather_code'][i]})"
            )
        return "\n".join(lines)


# --- RESOURCES (Application-Controlled) ---

@mcp.resource("weather://supported-cities")
async def list_supported_cities() -> str:
    """List of major cities with reliable weather data."""
    cities = [
        "Tokyo", "New York", "London", "Paris", "Sydney",
        "Berlin", "Toronto", "Singapore", "Dubai", "Seoul",
        "San Francisco", "Mumbai", "São Paulo", "Cairo", "Bangkok"
    ]
    return json.dumps({"cities": cities, "note": "Any city works, these are examples"})


# --- PROMPTS (User-Controlled) ---

@mcp.prompt()
def weather_report(city: str) -> str:
    """Generate a detailed weather report for a city."""
    return f"""Please provide a comprehensive weather report for {city}.
Include:
1. Current conditions (temperature, humidity, wind)
2. A {3}-day forecast
3. What to wear and any weather advisories
4. Best time of day for outdoor activities

Use the get_weather and get_forecast tools to gather the data,
then present it in a clear, friendly format."""


if __name__ == "__main__":
    mcp.run(transport="stdio")

The above constitutes a complete, runnable MCP server in approximately 80 lines of meaningful code. It exposes two tools (get_weather and get_forecast), one resource (weather://supported-cities) and one prompt (weather_report).

TypeScript MCP Server: Database Query Service

Step 1: Setup

# Create project
mkdir mcp-database-server && cd mcp-database-server
npm init -y
npm install @modelcontextprotocol/sdk better-sqlite3
npm install -D typescript @types/better-sqlite3 @types/node
npx tsc --init

Step 2: Create the server

Create src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import Database from "better-sqlite3";
import { z } from "zod";

// Open (or create) a SQLite database
const db = new Database("./data.db");

// Create a sample table for demonstration
db.exec(`
  CREATE TABLE IF NOT EXISTS products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT,
    price REAL,
    stock INTEGER
  )
`);

// Insert sample data if empty
const count = db.prepare("SELECT COUNT(*) as c FROM products").get() as any;
if (count.c === 0) {
  const insert = db.prepare(
    "INSERT INTO products (name, category, price, stock) VALUES (?, ?, ?, ?)"
  );
  const products = [
    ["Mechanical Keyboard", "Electronics", 149.99, 50],
    ["Ergonomic Mouse", "Electronics", 79.99, 120],
    ["4K Monitor", "Electronics", 599.99, 30],
    ["Standing Desk", "Furniture", 449.99, 15],
    ["Desk Lamp", "Furniture", 39.99, 200],
  ];
  for (const p of products) {
    insert.run(...p);
  }
}

// Create the MCP server
const server = new McpServer({
  name: "database-query",
  version: "1.0.0",
});

// --- TOOLS ---

server.tool(
  "query",
  "Execute a read-only SQL query against the database. Only SELECT statements are allowed. Use this when the user asks about products, inventory, or any data in the database.",
  {
    sql: z.string().describe("The SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Security: only allow SELECT queries
    const trimmed = sql.trim().toUpperCase();
    if (!trimmed.startsWith("SELECT")) {
      return {
        content: [
          { type: "text", text: "Error: Only SELECT queries are allowed." },
        ],
      };
    }

    try {
      const rows = db.prepare(sql).all();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(rows, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          { type: "text", text: `Query error: ${error.message}` },
        ],
      };
    }
  }
);

server.tool(
  "list_tables",
  "List all tables in the database with their schemas.",
  {},
  async () => {
    const tables = db
      .prepare(
        "SELECT name, sql FROM sqlite_master WHERE type='table' ORDER BY name"
      )
      .all();
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(tables, null, 2),
        },
      ],
    };
  }
);

server.tool(
  "describe_table",
  "Get the column information for a specific table.",
  {
    table_name: z.string().describe("Name of the table to describe"),
  },
  async ({ table_name }) => {
    try {
      const columns = db.prepare(`PRAGMA table_info(${table_name})`).all();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(columns, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          { type: "text", text: `Error: ${error.message}` },
        ],
      };
    }
  }
);

// --- Start the server ---
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Database MCP server running on stdio");
}

main().catch(console.error);

This TypeScript server exposes three tools for interacting with a SQLite database: query, which executes SELECT statements; list_tables, which discovers the schema; and describe_table, which inspects column details. It includes a security check that prevents non-SELECT queries from executing.

Step 3: Connect to Claude Desktop

To use an MCP server with Claude Desktop, the configuration file must be edited. On macOS it is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is located at %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/absolute/path/to/weather_server.py"]
    },
    "database": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"]
    }
  }
}

After saving the configuration and restarting Claude Desktop, the MCP tools icon appears in the chat interface. Claude then has access to the weather and database tools. The user may ask, for example, “What is the weather in Tokyo?” or “Show me all products in the database.” Claude will discover the appropriate tools, invoke them and present the results in natural language.

Step 4: Connect to Claude Code

For Claude Code, MCP servers are added to the project-level settings file at .claude/settings.json.

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/absolute/path/to/weather_server.py"]
    }
  }
}

Servers may alternatively be added at the user level in ~/.claude/settings.json so that they are available across all projects. Claude Code automatically discovers the tools at startup, and they are available in conversations in the same manner as the built-in tools.

Popular MCP Servers and the Ecosystem

One of the most notable aspects of MCP is the rapidly growing ecosystem of pre-built servers. Building every connector from scratch is unnecessary, as servers already exist for the most popular tools and services.

Official and Reference Servers

Anthropic and the MCP community maintain a collection of reference servers covering common use cases.

Discovering MCP Servers

Several directories and registries have emerged to assist in locating MCP servers.

• Smithery (smithery.ai): a curated registry of MCP servers with installation instructions and ratings.
• MCP Hub: a community-maintained directory with categories and search functionality.
• awesome-mcp-servers on GitHub: a curated list in the awesome-list tradition, organised by category.
• npm and PyPI: many MCP servers are published as packages installable via npm install or pip install.

MCP in Claude Code: A Detailed Examination

Claude Code is the context in which MCP is particularly relevant for developers. Claude Code is itself an MCP host, and its built-in capabilities, including Read, Write, Edit, Bash, Grep and Glob, are essentially MCP tools internally.

Built-In Tools as MCP

When Claude Code reads a file, edits code or runs a shell command, it uses the same tool-calling pattern that MCP standardises. The difference is that these tools are built directly into the Claude Code host rather than running as external MCP servers. The conceptual model is identical: the AI model sees a list of available tools with descriptions and schemas, determines which to invoke, generates the arguments and processes the result.

Claude Code was therefore designed from the outset to be extensible via MCP. Additional capabilities can be added to Claude Code simply by directing it to an MCP server.

Adding Custom MCP Servers

Two levels of MCP configuration exist in Claude Code.

Project-level configuration resides in .claude/settings.json within the project.

{
  "mcpServers": {
    "project-db": {
      "command": "python",
      "args": ["./tools/db_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/myapp"
      }
    }
  }
}

Project-level servers are only available when work is conducted in that specific project. This level is appropriate for project-specific tools such as database access, deployment scripts and custom linters.

User-level configuration resides in ~/.claude/settings.json.

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

User-level servers are available in every project. This level is appropriate for universal tools such as GitHub, Slack and Notion that are used across all work.

A Realistic Workflow Example

Consider a developer who has Claude Code configured with GitHub, Notion and Slack MCP servers. A representative workflow is as follows.

1. The developer instructs Claude Code: “Check the latest bug reports in our GitHub repository, summarise them in a Notion page, and post a summary to the #engineering Slack channel.”
2. Claude Code uses the GitHub MCP server to call list_issues with labels=[“bug”] and state=”open”.
3. It reads each issue’s details using get_issue.
4. It calls the Notion MCP server’s create_page tool with a structured summary.
5. It calls the Slack MCP server’s send_message tool to post to #engineering.
6. All of this occurs in a single conversation, using standard MCP tools, with no custom code.

This illustrates the value of MCP. Each server was constructed independently, potentially by different teams or open-source contributors. Because they all speak the same protocol, Claude Code can orchestrate them without friction.

MCP vs Other Approaches

MCP did not emerge in a vacuum. Several other approaches exist for connecting AI models with external tools. Understanding how MCP compares to these alternatives supports informed architectural decisions.

MCP vs OpenAI Function Calling

OpenAI’s function calling, alongside Anthropic’s tool use, allows developers to define tools in API calls and have the model generate structured arguments. The feature is powerful but provider-specific and requires custom integration code for each tool.

With function calling, the tool definitions and execution logic reside in application code. A GitHub integration built for an OpenAI-powered application cannot be reused in a Claude-powered application without rewriting it. The function definitions may appear similar, but the supporting code, including authentication, error handling and response formatting, is embedded in each application.

MCP separates tool definition and execution into a standalone server. A GitHub MCP server constructed once functions with any MCP host. The tool definitions travel with the server rather than with the application.

MCP vs OpenAI Plugins (Deprecated)

OpenAI Plugins, launched in 2023 and later deprecated, were an earlier attempt to address the same problem. Plugins used OpenAPI specifications to describe available endpoints, which ChatGPT could call. Plugins were, however, OpenAI-only, required the hosting of a public API endpoint with an OpenAPI specification, and presented significant security and reliability issues. MCP addresses each of these limitations: it is an open standard, it supports local servers without requiring public endpoints, and it provides a more robust security model.

MCP vs LangChain Tools

LangChain provides a framework for building AI applications, including a tool abstraction. LangChain tools are Python or JavaScript functions decorated with metadata. They are useful within the LangChain ecosystem but are framework-specific: a LangChain tool cannot be used outside LangChain without extracting the underlying logic.

MCP tools run as independent servers to which any MCP client may connect. They are language-agnostic, framework-agnostic and transport-agnostic. A Python MCP server functions with a TypeScript MCP client. A LangChain tool functions only within LangChain.

That said, LangChain has begun adding MCP integration, allowing MCP servers to be used as LangChain tools. The two approaches are converging rather than competing.

MCP vs Custom REST APIs

A natural question is why the AI model does not simply call REST APIs directly. The answer is that REST APIs were designed for machine-to-machine communication between known systems. They assume the developer knows the endpoint URL, the request format and the authentication method in advance. No standard discovery mechanism exists: documentation must be read and client code must be written.

MCP adds a discovery and negotiation layer. When an MCP client connects to a server, it automatically discovers the available tools, resources and prompts, together with their schemas. The AI model can then decide which tools to use on the basis of the descriptions. No custom client code is required.

Detailed Comparison Table

Security Considerations

Connecting AI models to tools and data is a powerful capability, and that power carries responsibility. MCP includes several security mechanisms, and understanding them is essential to building production-ready servers.

Tool Authorisation

Not every tool should be callable without review. MCP hosts implement authorisation policies that control which tools the model may invoke. In Claude Desktop, for example, a confirmation dialog appears when the model wishes to use a tool for the first time. The user may approve individual calls, approve all calls to a specific tool, or deny the request.

For production deployments, server-side authorisation should also be implemented. A client request for a tool call does not in itself oblige the server to execute it. Inputs should be validated, permissions checked, and access controls enforced.

Data Access Control

Resources expose data to the AI model, which means that sensitive data could potentially reach the model’s context window. MCP servers should be designed in accordance with the principle of least privilege:

• Expose only the data the AI genuinely requires.
• Implement row-level and column-level filtering.
• Redact sensitive fields (passwords, API keys, personally identifiable information) before they are returned.
• Use read-only database connections for query tools.

Credential Management

MCP servers frequently require credentials in order to access external APIs, including GitHub tokens, database passwords and API keys. Recommended practices include the following.

• Pass credentials via environment variables rather than command-line arguments, which may appear in process listings.
• Use secrets managers such as AWS Secrets Manager or HashiCorp Vault for production deployments.
• Rotate credentials regularly.
• Never log credentials.

Sandboxing and Audit Logging

For tools that execute code or run shell commands, sandboxing is important. The following measures should be considered.

• Run MCP servers in containers with limited permissions.
• Use filesystem access controls to restrict which directories are accessible.
• Implement timeout mechanisms for long-running operations.
• Log every tool call with its inputs and outputs for audit purposes.
• Implement rate limiting to prevent abuse.

User Consent Model

The MCP specification encourages a user consent model in which potentially hazardous operations require explicit approval. Before a tool deletes a file, sends an email or deploys code, the user should be asked to confirm. Most MCP hosts implement this at the UI level, but server-side safeguards form an important additional layer.

Building Production MCP Servers

Moving from a prototype MCP server to a production-ready one involves several engineering concerns.

Error Handling

MCP tools should never raise unhandled exceptions. Errors should be caught, descriptive error messages returned, and the isError flag in tool results used to signal failures.

@mcp.tool()
async def query_database(sql: str) -> str:
    """Execute a SQL query."""
    try:
        # Validate input
        if not sql.strip().upper().startswith("SELECT"):
            return "Error: Only SELECT queries are allowed for safety."

        # Execute with timeout
        result = await asyncio.wait_for(
            execute_query(sql),
            timeout=30.0
        )
        return json.dumps(result, default=str)

    except asyncio.TimeoutError:
        return "Error: Query timed out after 30 seconds. Try a simpler query."
    except sqlite3.OperationalError as e:
        return f"SQL Error: {e}. Check your query syntax."
    except Exception as e:
        logger.exception("Unexpected error in query_database")
        return f"Internal error: {type(e).__name__}. The issue has been logged."

Logging and Monitoring

For MCP servers, logs should be written to stderr rather than stdout, which is reserved for the JSON-RPC protocol when stdio transport is used. Structured logging should include request IDs, tool names, execution times and error details. For HTTP-based servers, integration with standard monitoring tools such as Prometheus, Grafana or Datadog is recommended.

Testing

MCP servers should be tested at multiple levels.

• Unit tests: individual tool functions are tested with known inputs and expected outputs.
• Integration tests: the MCP SDK’s test client is used to simulate the complete protocol flow (initialize, list tools, call tool, verify result).
• End-to-end tests: a real MCP host such as Claude Code is connected to the server and the complete workflow is verified.

# Example: Testing with the MCP SDK's test utilities
import pytest
from mcp.client.session import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters

@pytest.mark.asyncio
async def test_weather_tool():
    server_params = StdioServerParameters(
        command="python",
        args=["weather_server.py"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            tool_names = [t.name for t in tools.tools]
            assert "get_weather" in tool_names

            # Call the weather tool
            result = await session.call_tool(
                "get_weather",
                arguments={"city": "London"}
            )
            assert "London" in result.content[0].text
            assert "Temperature" in result.content[0].text

Deployment Options

MCP servers can be deployed in several ways, depending on requirements.

• Local binary or script: the simplest option. The server script is distributed and users run it locally via stdio. This option is well suited to personal tools and open-source distribution.
• Docker container: the server is packaged with all dependencies. Users pull the image and point their MCP client at the container. This approach provides consistency across environments.
• Cloud function: deployment as an AWS Lambda, Google Cloud Function or Azure Function, using the HTTP+SSE transport. Scales automatically with pay-per-invocation pricing.
• Dedicated service: the server runs as a persistent web service on Kubernetes, ECS or a virtual machine. This deployment model is best suited to high-traffic, low-latency or shared team scenarios.

The Future of MCP

MCP remains in its early phase, but the trajectory is clear. The following directions are particularly noteworthy.

Growing Industry Adoption

MCP is no longer solely Anthropic’s project. Microsoft has added MCP support to VS Code and GitHub Copilot. Google has indicated interest. The open-source community is producing hundreds of servers. When major competitors adopt a common standard, the standard has typically prevailed. HTTP, JSON and SQL share the same trajectory: no single company owns them, which is precisely why they dominate.

MCP Marketplaces

Just as app stores transformed mobile platforms and browser extension stores transformed the web, MCP marketplaces are emerging. Smithery.ai is an early example: a registry that allows users to discover, install and rate MCP servers. More polished marketplaces with one-click installation, security audits and verified publishers can be expected.

Server-to-Server Communication

The current MCP model is host-to-server: an AI application connects to MCP servers. A natural extension concerns AI agents that use other agents’ tools. Server-to-server MCP communication would enable composable AI systems in which a planning agent delegates tasks to specialised agents, each with its own MCP tools. This is the architecture that will support complex, multi-step AI workflows.

Authentication Standards

OAuth integration for MCP is under active development. This will permit MCP servers to use standard OAuth flows for authentication, simplifying the construction of servers that access user data from third-party services such as Google, Microsoft and Salesforce with appropriate authorisation. Users will no longer be required to generate personal access tokens manually.

Streaming and Performance

Current MCP tools return complete results. Planned improvements include streaming results, which are useful for large dataset queries or real-time data, progress reporting for long-running operations, and partial results that the model can begin processing before the tool finishes. The newer Streamable HTTP transport is a step in this direction.

The Interface Layer for AI

As AI models that can reason, plan and act autonomously become more capable, they will require a standardised way to interact with the digital world. MCP is positioning itself as that interface layer. Just as operating systems provide a standardised interface between applications and hardware, MCP provides a standardised interface between AI models and tools. The model does not need to know how GitHub’s API operates. It only needs to know how to speak MCP.

Getting Started: Your Next Steps

The reader now understands what MCP is, how it operates architecturally, what the three primitives do, how the transport layer functions, and how to build servers in both Python and TypeScript. The following steps support practical application of that knowledge.

Try a Pre-Built MCP Server

The fastest way to experience MCP is to install Claude Desktop and add a pre-built server. The filesystem server is a useful starting point, since it enables Claude to read and search files on the user’s computer.

// claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    }
  }
}

Restart Claude Desktop and then ask: “What files are in my Documents folder?” Claude will use the filesystem MCP server to respond.

Build Your Own Server

One of the examples in this article, either the Python weather server or the TypeScript database server, can be taken as a starting point and adapted to a specific use case. Potential applications include a server that queries an internal API, searches personal notes or manages a task list. Begin simply: one or two tools, stdio transport and local execution.

Integrate with the Development Workflow

Developers who use Claude Code may add MCP servers that enhance the development workflow. The GitHub server allows Claude to create issues and pull requests. A database server allows Claude to query the development database. A deployment server may allow Claude to trigger deployments. Each additional server expands Claude Code’s capabilities without requiring changes to Claude Code itself.

Contribute to the Ecosystem

The MCP ecosystem is still young, which creates substantial opportunities to contribute. A developer may build a server for a tool or service that does not yet have one, improve an existing server with better error handling, additional tools or documentation, or submit a pull request to the specification when a use case is found to be inadequately covered.

Essential Resources

• MCP Specification: spec.modelcontextprotocol.io, the authoritative source for the protocol.
• MCP Documentation: modelcontextprotocol.io, containing guides, tutorials and SDK references.
• Python SDK: pip install mcp, the official Python SDK including FastMCP.
• TypeScript SDK: npm install @modelcontextprotocol/sdk, the official TypeScript SDK.
• Reference Servers: github.com/modelcontextprotocol/servers, hosting official and community servers.
• Claude Code Documentation: docs.anthropic.com/en/docs/claude-code, including MCP configuration guidance.

Final Thoughts

The Model Context Protocol is one of those rare technologies that addresses a problem so fundamental that, once understood, the prior state seems untenable. Before MCP, connecting AI to tools was an artisanal craft: hand-built, fragile and duplicated endlessly across every application and every vendor. After MCP, it is an engineering discipline: standardised, composable and reusable.

The N times M problem is real. Every AI company was constructing the same GitHub integration, the same Slack integration and the same database connector, each slightly different, each maintained separately, each failing in its own way. MCP collapses that complexity into N plus M, and the results are already visible: hundreds of servers, dozens of compatible hosts, and a community that is expanding faster than almost any open-source project in the AI space.

MCP is more than an engineering convenience, however. It represents a conceptual shift in how AI capabilities are organised. Rather than building monolithic AI applications that attempt to perform every function, MCP enables a modular architecture in which capabilities are distributed across specialised servers. Weather data has a server. GitHub access has a server. A query interface for a proprietary database can be constructed in an afternoon.

The analogy with HTTP is not hyperbole. HTTP did not merely simplify the retrieval of web pages; it enabled an entire ecosystem of web servers, web applications, CDNs, APIs and services that no one could have predicted in 1991. MCP carries the same potential. The AI tooling ecosystem is at its beginning, and MCP is the protocol that will underpin it.

Developers should consider building MCP servers. Companies with internal tools should consider exposing them via MCP. Organisations evaluating AI platforms should prioritise those that support MCP. The protocol is open, the SDKs are mature and the ecosystem is ready. What remains is the server.

References

• Anthropic. “Introducing the Model Context Protocol.” Anthropic Blog, November 2024. anthropic.com/news/model-context-protocol
• Model Context Protocol. “MCP Specification.” spec.modelcontextprotocol.io
• Model Context Protocol. “Documentation and Guides.” modelcontextprotocol.io
• GitHub. “Model Context Protocol Servers Repository.” github.com/modelcontextprotocol/servers
• Anthropic. “Claude Code Documentation.” docs.anthropic.com/en/docs/claude-code
• Microsoft. “Language Server Protocol.” microsoft.github.io/language-server-protocol
• JSON-RPC Working Group. “JSON-RPC 2.0 Specification.” jsonrpc.org/specification

Disclaimer: This article is for informational and educational purposes only. References to specific companies, products, or technologies do not constitute endorsements. Technology landscapes evolve rapidly—always verify details against official documentation.

In March 2023, a developer built a ChatGPT-powered assistant that could check the weather, look up flight prices, and book restaurant reservations within a single conversation. The mechanism deserves scrutiny: the AI itself never called a single API. Instead, it told the developer’s code exactly which function to call and with which arguments, received the results, and incorporated them into a seamless natural language response. The user could not have known that they were conversing with a text generator unable to act on its own. The mechanism has a name: tool calling. It is the single most important capability that transformed large language models from impressive text generators into agents capable of interacting with the real world.

A central limitation of LLMs warrants direct acknowledgement: they are fundamentally constrained. An LLM does not know today’s date. It cannot check a stock price. It cannot query a database, send an email, or read a file on the user’s computer. It knows only what was in its training data (which is months or years old) and whatever appears in the current conversation. Without tool calling, asking an LLM “What is NVIDIA’s stock price now?” yields a polite apology and a reminder of its knowledge cutoff date.

Tool calling changed this situation. It is the mechanism that allows an AI model to indicate, “I do not know the answer, but I know which function to call to obtain it, and here are the exact arguments.” The user’s code then executes that function, feeds the result back to the model, and the model responds as if it had known all along. This is how ChatGPT plugins operate, how Claude Code reads and writes files, and how every AI agent functions internally.

This guide examines tool calling from the ground up. It explains exactly how the mechanism works, presents complete code examples for Claude and OpenAI, describes the differences between providers, and provides what is required to build tool-calling applications. For developers building AI-powered products and for analysts evaluating AI companies, understanding tool calling is essential: it is the bridge between “AI that talks” and “AI that acts.”

What Is Tool Calling

Tool calling (also referred to as function calling) is a mechanism by which a large language model can request the execution of external functions or APIs during a conversation. Rather than attempting to answer entirely from memory, the model can reach into the real world—checking databases, calling APIs, performing calculations, or executing code—by asking the application to run specific functions on its behalf.

The central insight is deceptively simple: the model does not execute the tools itself. It generates a structured request—a function name plus arguments in JSON format—and the user’s code is responsible for actually executing it. The result is sent back to the model, which then incorporates it into its response.

The relationship can be likened to that of a brain and hands. The LLM is the brain: it plans, reasons, and decides what should happen. The tools are the hands: they perform actions in the world. The brain cannot lift a cup of coffee by itself, but it can direct the hands precisely. Similarly, an LLM cannot check the weather directly, but it can instruct a code path to call a weather API with specific coordinates and then interpret the result.

The Three-Step Loop

Every tool calling interaction follows the same fundamental pattern:

The full flow is described step by step below:

┌─────────┐    "What's the weather     ┌─────────┐
│         │    in Tokyo?"              │         │
│  User   │ ──────────────────────────→│  Your   │
│         │                            │  App    │
└─────────┘                            └────┬────┘
                                            │
                           Sends message +  │
                           tool definitions │
                                            ▼
                                       ┌─────────┐
                                       │         │
                                       │  LLM    │
                                       │  (API)  │
                                       └────┬────┘
                                            │
                           Returns:         │
                           tool_use:        │
                           get_weather      │
                           {"city":"Tokyo"} │
                                            ▼
                                       ┌─────────┐
                                       │  Your   │
                                       │  App    │──→ Calls weather API
                                       │(execute)│←── Gets result: 22°C
                                       └────┬────┘
                                            │
                           Sends tool_result│
                           back to LLM     │
                                            ▼
                                       ┌─────────┐
                                       │  LLM    │
                                       │  (API)  │
                                       └────┬────┘
                                            │
                           Final response:  │
                           "It's 22°C and   │
                            sunny in Tokyo" │
                                            ▼
                                       ┌─────────┐
                                       │  User   │
                                       │  sees   │
                                       │ response│
                                       └─────────┘

Why This Is a Significant Development

Before tool calling: LLMs could only generate text. They were highly capable in that respect, but they were fundamentally disconnected from the world. A request for today’s weather produced a hallucinated guess or an apology. A request to send an email produced a draft that the user had to copy and send manually.

After tool calling: LLMs can take actions. They can check real-time data, interact with databases, control software, browse the web, manage files, send messages, and orchestrate complex multi-step workflows. The same text-generation capability previously limited to chat responses now drives decision-making about which actions to take and how to interpret the results.

This single capability—the ability for a model to say “call this function with these arguments”—is what turned LLMs from chatbots into agents. Every AI agent framework, every chatbot plugin system, and every autonomous AI workflow is built on tool calling.

How Tool Calling Works Internally

The following walkthrough describes each step of the tool calling process in detail, using the actual data structures encountered when building with these APIs.

Step 1: Tool Definition

Before the model can use any tools, the available tools must be declared. This is done by including a tool definition in the API request. Each tool definition is a JSON Schema describing the function’s name, purpose, and parameters.

{
  "name": "get_current_weather",
  "description": "Get the current weather conditions for a specific city. Returns temperature in Celsius, weather condition, humidity, and wind speed. Use this when the user asks about current weather, temperature, or atmospheric conditions for any location.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The city name, e.g. 'Tokyo', 'New York', 'London'"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature units. Defaults to celsius.",
        "default": "celsius"
      }
    },
    "required": ["city"]
  }
}

The description is critically important: it is what the model reads to determine when to use a given tool. A vague description such as “weather stuff” will lead the model to use the tool at the wrong times, or not at all when it should. A detailed description, like the one above, supports precise decisions.

Step 2: Tool Selection

When the model receives a user message along with tool definitions, it makes a decision: respond directly, or call one or more tools first. This decision is made by the model itself; it is part of the model’s inference process, not a separate system.

The model considers the following questions:

• Does the user’s request require information that the model does not have?
• Is there a tool that can provide that information?
• What arguments should be passed to the tool?
• Are multiple tool calls required?
• Should tools be called in parallel or sequentially?

If the user asks “What is 2 + 2?”, the model answers directly, with no tool needed. If the user asks “What is the weather in Tokyo?” and a get_current_weather tool is available, the model will determine that the tool should be called.

Step 3: Structured Output

When the model decides to call a tool, it does not output free-form text. Instead, it outputs a structured tool_use block with the function name and arguments as valid JSON:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_current_weather",
      "input": {
        "city": "Tokyo",
        "units": "celsius"
      }
    }
  ]
}

This is not a suggestion or a natural language request; it is a precisely structured instruction. The function name matches exactly what was defined, and the arguments conform to the JSON Schema provided. This is what makes tool calling reliable: the model does not say “maybe try checking the weather”; it says “call get_current_weather with {"city": "Tokyo", "units": "celsius"}“.

Step 4: Execution

The application code receives this tool_use block, parses it, and executes the actual function. This is where the real work occurs: the API call is made, the database query is run, the calculation is performed, or whatever else the tool does:

# Your code — NOT the model's code
def get_current_weather(city: str, units: str = "celsius") -> dict:
    response = requests.get(
        f"https://api.openweathermap.org/data/2.5/weather",
        params={"q": city, "units": "metric", "appid": API_KEY}
    )
    data = response.json()
    return {
        "city": city,
        "temperature": data["main"]["temp"],
        "condition": data["weather"][0]["description"],
        "humidity": data["main"]["humidity"],
        "wind_speed": data["wind"]["speed"]
    }

Step 5: Result Injection

The tool result is sent back to the model as a tool_result message:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "{\"city\": \"Tokyo\", \"temperature\": 22, \"condition\": \"clear sky\", \"humidity\": 45, \"wind_speed\": 3.6}"
    }
  ]
}

Step 6: Final Response

The model reads the tool result and generates a natural language response for the user. The model does not simply repeat the raw data; it interprets the data, adds context, and presents it conversationally:

“At present in Tokyo the temperature is 22°C with clear skies. Humidity is 45%, and there is a light breeze at 3.6 m/s.”

Multi-Tool and Iterative Tool Use

Modern models can call multiple tools in a single turn. If a user asks “What is the weather in Tokyo and New York?”, the model can output two tool_use blocks simultaneously—a parallel tool call. The application executes both and returns both results.

Models can also use tools iteratively. In a complex task, the model may call tool A, examine the result, determine that more information is required, call tool B, examine that result, and only then respond. This iterative capability is the foundation of AI agents: the model continues to call tools in a loop until it has enough information to complete the task.

Tool Calling Across Major AI Providers

The core concept is the same across providers, although the API formats differ. The following sections present complete, runnable examples for each major provider.

Anthropic Claude (Messages API)

Claude’s tool calling uses a clean, content-block-based format. Tools are defined with input_schema (standard JSON Schema), and the model responds with tool_use content blocks.

A complete, runnable Python example follows:

import anthropic
import json

client = anthropic.Anthropic()  # Uses ANTHROPIC_API_KEY env var

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city. Returns temperature (Celsius), condition, humidity, and wind speed.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "City name, e.g. 'Tokyo', 'London'"
                }
            },
            "required": ["city"]
        }
    },
    {
        "name": "get_stock_price",
        "description": "Get the current stock price for a given ticker symbol. Returns price in USD, daily change, and percentage change.",
        "input_schema": {
            "type": "object",
            "properties": {
                "ticker": {
                    "type": "string",
                    "description": "Stock ticker symbol, e.g. 'AAPL', 'NVDA', 'GOOGL'"
                }
            },
            "required": ["ticker"]
        }
    }
]

# Simulated tool implementations
def get_weather(city: str) -> dict:
    # In production, call a real weather API
    return {"city": city, "temperature": 22, "condition": "sunny", "humidity": 45}

def get_stock_price(ticker: str) -> dict:
    # In production, call a real stock API
    return {"ticker": ticker, "price": 875.30, "change": +12.50, "percent_change": "+1.45%"}

# Map function names to implementations
tool_functions = {
    "get_weather": get_weather,
    "get_stock_price": get_stock_price,
}

# Send initial message with tools
messages = [{"role": "user", "content": "What's the weather in Tokyo and NVIDIA's stock price?"}]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(f"Stop reason: {response.stop_reason}")

# Process tool calls
while response.stop_reason == "tool_use":
    # Collect all tool use blocks
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            # Execute the tool
            func = tool_functions[block.name]
            result = func(**block.input)
            print(f"Called {block.name}({block.input}) → {result}")

            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })

    # Send results back to Claude
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        tools=tools,
        messages=messages
    )

# Print final response
for block in response.content:
    if hasattr(block, "text"):
        print(f"\nClaude's response:\n{block.text}")

Claude-specific features:

• Parallel tool calls. Claude can output multiple tool_use blocks in a single response, allowing parallel execution.
• Streaming with tools. Tool calls work with streaming; the application receives content_block_start events for tool_use blocks as they are generated.
• Tool choice control. Fine-grained control over when the model uses tools via tool_choice.
• Large tool sets. Claude handles large numbers of tools well, though keeping the count below approximately 20 is recommended for optimal performance.

OpenAI GPT (Chat Completions API)

OpenAI’s format uses a tools array with type: "function" wrappers. The response includes a tool_calls array, and results are sent back as messages with role: "tool".

from openai import OpenAI
import json

client = OpenAI()  # Uses OPENAI_API_KEY env var

# Define tools — note the different format from Claude
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'Tokyo'"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Get the current stock price for a ticker symbol.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "Stock ticker, e.g. 'NVDA'"
                    }
                },
                "required": ["ticker"]
            }
        }
    }
]

# Same tool implementations as above
def get_weather(city):
    return {"city": city, "temperature": 22, "condition": "sunny"}

def get_stock_price(ticker):
    return {"ticker": ticker, "price": 875.30, "change": "+1.45%"}

tool_functions = {"get_weather": get_weather, "get_stock_price": get_stock_price}

messages = [{"role": "user", "content": "What's the weather in Tokyo and NVIDIA's stock price?"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message

# Process tool calls
while message.tool_calls:
    messages.append(message)  # Add assistant message with tool calls

    for tool_call in message.tool_calls:
        func = tool_functions[tool_call.function.name]
        args = json.loads(tool_call.function.arguments)
        result = func(**args)

        # Note: OpenAI uses role="tool" instead of tool_result content blocks
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools
    )
    message = response.choices[0].message

print(message.content)

Google Gemini

Gemini’s function calling follows a similar pattern but uses its own API format. Tool definitions use FunctionDeclaration objects, and responses include function_call parts. Gemini supports both automatic and manual function calling modes and can handle parallel function calls, as Claude and GPT do.

The principal difference with Gemini is its tight integration with the Google ecosystem: function calling works seamlessly with Google Search, Google Maps, and other Google APIs as built-in tools.

Provider Comparison

Practical Tool Calling Examples (with Complete Code)

The following four examples build progressively more complex tool calling patterns.

Example 1: Chained Tools—Weather by City Name

This example illustrates tool chaining: the model calls one tool to obtain coordinates, then uses those coordinates to call a second tool for weather data. The model autonomously determines that both calls are required.

import anthropic
import json
import requests

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_coordinates",
        "description": "Convert a city name to latitude/longitude coordinates using geocoding.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
                "country_code": {"type": "string", "description": "ISO country code, e.g. 'FR'"}
            },
            "required": ["city"]
        }
    },
    {
        "name": "get_weather_by_coords",
        "description": "Get weather data for specific latitude/longitude coordinates.",
        "input_schema": {
            "type": "object",
            "properties": {
                "latitude": {"type": "number", "description": "Latitude coordinate"},
                "longitude": {"type": "number", "description": "Longitude coordinate"}
            },
            "required": ["latitude", "longitude"]
        }
    }
]

API_KEY = "your_openweathermap_api_key"

def get_coordinates(city: str, country_code: str = None) -> dict:
    params = {"q": city if not country_code else f"{city},{country_code}",
              "limit": 1, "appid": API_KEY}
    resp = requests.get("http://api.openweathermap.org/geo/1.0/direct", params=params)
    data = resp.json()[0]
    return {"city": data["name"], "lat": data["lat"], "lon": data["lon"],
            "country": data["country"]}

def get_weather_by_coords(latitude: float, longitude: float) -> dict:
    params = {"lat": latitude, "lon": longitude, "units": "metric", "appid": API_KEY}
    resp = requests.get("https://api.openweathermap.org/data/2.5/weather", params=params)
    data = resp.json()
    return {
        "temperature": data["main"]["temp"],
        "feels_like": data["main"]["feels_like"],
        "condition": data["weather"][0]["description"],
        "humidity": data["main"]["humidity"],
        "wind_speed": data["wind"]["speed"]
    }

tool_map = {"get_coordinates": get_coordinates, "get_weather_by_coords": get_weather_by_coords}

def chat_with_tools(user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-20250514", max_tokens=1024,
            tools=tools, messages=messages
        )

        if response.stop_reason == "end_turn":
            return "".join(b.text for b in response.content if hasattr(b, "text"))

        # Process tool calls
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = tool_map[block.name](**block.input)
                print(f"  Tool: {block.name}({block.input}) → {result}")
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                })

        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

# The model will first call get_coordinates("Paris"),
# then use the result to call get_weather_by_coords(48.85, 2.35)
print(chat_with_tools("What's the weather like in Paris right now?"))

The model is not instructed to chain these calls. It reads the tool descriptions, recognises that get_weather_by_coords requires coordinates, and autonomously calls get_coordinates first. This represents emergent reasoning rather than hard-coded logic.

Example 2: Database Query Tool

This example provides the model with the ability to query a SQLite database. The model generates SQL, the tool executes it safely, and the model interprets the results.

import anthropic
import json
import sqlite3

client = anthropic.Anthropic()

# Create a sample database
conn = sqlite3.connect(":memory:")
cursor = conn.cursor()
cursor.executescript("""
    CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT,
                        signup_date DATE, plan TEXT);
    INSERT INTO users VALUES (1, 'Alice', 'alice@example.com', '2026-03-15', 'pro');
    INSERT INTO users VALUES (2, 'Bob', 'bob@example.com', '2026-03-20', 'free');
    INSERT INTO users VALUES (3, 'Charlie', 'charlie@example.com', '2026-02-10', 'pro');
    INSERT INTO users VALUES (4, 'Diana', 'diana@example.com', '2026-03-25', 'enterprise');
    INSERT INTO users VALUES (5, 'Eve', 'eve@example.com', '2026-01-05', 'free');

    CREATE TABLE orders (id INTEGER PRIMARY KEY, user_id INTEGER,
                         amount DECIMAL, order_date DATE);
    INSERT INTO orders VALUES (1, 1, 99.99, '2026-03-16');
    INSERT INTO orders VALUES (2, 3, 199.99, '2026-03-01');
    INSERT INTO orders VALUES (3, 4, 499.99, '2026-03-26');
    INSERT INTO orders VALUES (4, 1, 49.99, '2026-03-28');
""")

tools = [
    {
        "name": "query_database",
        "description": """Execute a READ-ONLY SQL query against the database.
Available tables:
- users (id, name, email, signup_date, plan) — plan is 'free', 'pro', or 'enterprise'
- orders (id, user_id, amount, order_date) — user_id references users.id
Only SELECT statements are allowed. Returns rows as a list of dictionaries.""",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "SQL SELECT query to execute"
                }
            },
            "required": ["query"]
        }
    }
]

def query_database(query: str) -> dict:
    # Security: only allow SELECT statements
    if not query.strip().upper().startswith("SELECT"):
        return {"error": "Only SELECT queries are allowed"}

    try:
        cursor.execute(query)
        columns = [desc[0] for desc in cursor.description]
        rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
        return {"columns": columns, "rows": rows, "row_count": len(rows)}
    except Exception as e:
        return {"error": str(e)}

# Ask a natural language question about the data
messages = [{"role": "user", "content": "How many users signed up in March 2026, and what's the total revenue from orders that month?"}]

response = client.messages.create(
    model="claude-sonnet-4-20250514", max_tokens=1024,
    tools=tools, messages=messages
)

# Process (the model will likely make two queries)
while response.stop_reason == "tool_use":
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = query_database(**block.input)
            print(f"SQL: {block.input['query']}")
            print(f"Result: {result}\n")
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })

    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})
    response = client.messages.create(
        model="claude-sonnet-4-20250514", max_tokens=1024,
        tools=tools, messages=messages
    )

for block in response.content:
    if hasattr(block, "text"):
        print(block.text)

Example 3: Multi-Tool Agent

This example builds a small agent that can search the web, read URLs, and send emails. It demonstrates the agentic loop: the model calls tools iteratively until the task is complete.

import anthropic
import json

client = anthropic.Anthropic()

tools = [
    {
        "name": "search_web",
        "description": "Search the web for current information. Returns a list of results with titles, URLs, and snippets.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"}
            },
            "required": ["query"]
        }
    },
    {
        "name": "read_url",
        "description": "Read the text content of a web page given its URL.",
        "input_schema": {
            "type": "object",
            "properties": {
                "url": {"type": "string", "description": "Full URL to read"}
            },
            "required": ["url"]
        }
    },
    {
        "name": "send_email",
        "description": "Send an email to a recipient with a subject and body.",
        "input_schema": {
            "type": "object",
            "properties": {
                "to": {"type": "string", "description": "Recipient email address"},
                "subject": {"type": "string", "description": "Email subject line"},
                "body": {"type": "string", "description": "Email body (plain text)"}
            },
            "required": ["to", "subject", "body"]
        }
    }
]

# Simulated tool implementations
def search_web(query):
    return {"results": [
        {"title": "NVIDIA Q4 2026 Earnings", "url": "https://example.com/nvidia-earnings",
         "snippet": "NVIDIA reported revenue of $45B, up 78% YoY..."},
        {"title": "NVIDIA Earnings Analysis", "url": "https://example.com/nvidia-analysis",
         "snippet": "Data center revenue drove growth at $38B..."}
    ]}

def read_url(url):
    return {"content": "NVIDIA reported Q4 2026 revenue of $45 billion, beating estimates of $42B. "
            "Data center revenue reached $38B (+95% YoY). Gaming revenue was $4.2B (+15%). "
            "Gross margin was 73.5%. The company announced a $50B buyback program."}

def send_email(to, subject, body):
    return {"status": "sent", "message_id": "msg_abc123"}

tool_map = {"search_web": search_web, "read_url": read_url, "send_email": send_email}

def run_agent(task: str, max_iterations: int = 10) -> str:
    """Run the agent loop until task completion or max iterations."""
    messages = [{"role": "user", "content": task}]

    for i in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-4-20250514", max_tokens=4096,
            tools=tools, messages=messages
        )

        if response.stop_reason == "end_turn":
            return "".join(b.text for b in response.content if hasattr(b, "text"))

        # Execute all tool calls
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = tool_map[block.name](**block.input)
                print(f"  [{i+1}] {block.name}({json.dumps(block.input)[:80]}...)")
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                })

        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

    return "Max iterations reached"

# The agent will: search → read article → compose email → send
result = run_agent(
    "Research the latest NVIDIA earnings and email a summary to investor@example.com"
)
print(result)

The run_agent function is a simple while loop that continues calling the model until the task is complete. The model autonomously determines the sequence: search first, read the most relevant article, compose an email, and send it. This is the core pattern underlying every AI agent framework.

Example 4: Calculator and Code Execution

LLMs are notably poor at arithmetic. Tool calling resolves this by offloading computation to actual code:

import anthropic
import json
import math

client = anthropic.Anthropic()

tools = [
    {
        "name": "calculate",
        "description": "Evaluate a mathematical expression. Supports standard math operations (+, -, *, /, **, %), functions (sqrt, sin, cos, log, abs), and constants (pi, e). Examples: '2**10', 'sqrt(144)', 'log(1000, 10)'",
        "input_schema": {
            "type": "object",
            "properties": {
                "expression": {"type": "string", "description": "Math expression to evaluate"}
            },
            "required": ["expression"]
        }
    },
    {
        "name": "run_python",
        "description": "Execute a Python code snippet and return stdout output. Use for complex calculations, data processing, or generating formatted results. The code runs in a sandboxed environment.",
        "input_schema": {
            "type": "object",
            "properties": {
                "code": {"type": "string", "description": "Python code to execute"}
            },
            "required": ["code"]
        }
    }
]

def calculate(expression: str) -> dict:
    # Safe math evaluation with limited namespace
    allowed = {k: v for k, v in math.__dict__.items() if not k.startswith('_')}
    allowed.update({"abs": abs, "round": round, "min": min, "max": max})
    try:
        result = eval(expression, {"__builtins__": {}}, allowed)
        return {"expression": expression, "result": result}
    except Exception as e:
        return {"error": str(e)}

def run_python(code: str) -> dict:
    # WARNING: In production, use a proper sandbox (Docker, gVisor, etc.)
    import io, contextlib
    output = io.StringIO()
    try:
        with contextlib.redirect_stdout(output):
            exec(code, {"__builtins__": __builtins__})
        return {"stdout": output.getvalue(), "status": "success"}
    except Exception as e:
        return {"error": str(e), "status": "error"}

tool_map = {"calculate": calculate, "run_python": run_python}

# Ask something that requires precise computation
messages = [{"role": "user", "content":
    "If I invest $10,000 at 7.5% annual return compounded monthly, "
    "how much will I have after 20 years? Show the year-by-year breakdown."}]

response = client.messages.create(
    model="claude-sonnet-4-20250514", max_tokens=4096,
    tools=tools, messages=messages
)

while response.stop_reason == "tool_use":
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = tool_map[block.name](**block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": json.dumps(result)
            })
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": tool_results})
    response = client.messages.create(
        model="claude-sonnet-4-20250514", max_tokens=4096,
        tools=tools, messages=messages
    )

for block in response.content:
    if hasattr(block, "text"):
        print(block.text)

The Agentic Loop: From Tool Calling to AI Agents

Tool calling is a single request-response interaction. An AI agent is what results when tool calling is placed within a loop. The agent continues to think, call tools, observe results, and think again, until the task is complete.

The Basic Agent Loop

while task is not complete:
    1. THINK    → Model analyzes the current state and decides what to do next
    2. SELECT   → Model chooses a tool and generates arguments
    3. EXECUTE  → Application runs the tool and captures the result
    4. OBSERVE  → Result is fed back to the model
    5. REPEAT   → Model decides: need more info? Call another tool. Done? Respond.

┌──────────────────────────────────────────────┐
│                AGENT LOOP                     │
│                                               │
│  ┌─────────┐     ┌──────────┐    ┌─────────┐ │
│  │  THINK  │────→│  SELECT  │───→│ EXECUTE │ │
│  │         │     │   TOOL   │    │  TOOL   │ │
│  └────▲────┘     └──────────┘    └────┬────┘ │
│       │                               │      │
│       │         ┌──────────┐          │      │
│       └─────────│ OBSERVE  │◀─────────┘      │
│                 │  RESULT  │                  │
│                 └─────┬────┘                  │
│                       │                       │
│              Done? ───┤                       │
│              No  ─────┘ (loop back)           │
│              Yes ─────→ RESPOND to user       │
└──────────────────────────────────────────────┘

This pattern is widespread:

• Claude Code—the tool through which a reader may be encountering this post—uses exactly this pattern. When Claude Code is asked to fix a bug in auth.py, it calls tools such as Read (to read files), Grep (to search code), Edit (to modify files), and Bash (to run tests), iterating until the bug is fixed.
• ChatGPT with plugins follows the same loop: the model decides which plugins to invoke, executes them, reads the results, and continues.
• GitHub Copilot’s agent mode reads the codebase, makes edits, runs tests, and iterates—all through tool calling.

How Claude Code Uses Tool Calling

Claude Code is an effective real-world example. Given a task, it has access to tools such as:

A typical Claude Code session may involve 20 to 50 tool calls for a single task. The model reads a file, identifies the problem, searches for related code, makes an edit, runs the tests, observes a test failure, reads the error, makes another edit, runs the tests again, and finally reports success. Every step is a tool call. The intelligence is in determining which tool to call and which arguments to use; the actual execution is performed by the user’s computer.

The Progression: Tool Call to Agent

Understanding tool calling makes the full progression of AI capability visible:

1. Simple tool call: A user asks a question, the model calls one tool, and the model responds. (Weather lookup.)
2. Multi-tool call: The model calls several tools in parallel or sequence within a single turn. (Weather plus stock price.)
3. Multi-step chain: The model calls tools iteratively across multiple turns, using each result to inform the next call. (Research, read, summarise, email.)
4. Autonomous agent: The model operates in a loop with minimal human intervention, using tools to accomplish complex goals. (Claude Code fixing a bug across multiple files.)

Each step builds on the one before. Understanding step 1 establishes the foundation for step 4. Tool calling is the atomic unit of AI agency.

Model Context Protocol (MCP): The Standard for Tool Calling

If every AI application defines its tools in a different format, the ecosystem becomes fragmented. The Model Context Protocol (MCP) addresses this problem.

MCP is an open standard, developed by Anthropic, that provides a universal way to connect AI models to external tools, data sources, and services. It can be understood as a USB-C equivalent for AI tools: a single standard that works across systems, in place of each system requiring its own proprietary connector.

How MCP Works

MCP defines a client-server architecture:

• MCP Clients (such as Claude Code, Claude Desktop, or a custom application) connect to MCP servers and expose the available tools to the AI model.
• MCP Servers expose three types of capabilities:
  • Tools: Functions the model can call (the same concept as function calling).
  • Resources: Data the model can read (files, database records, API responses).
  • Prompts: Pre-defined prompt templates for common tasks.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Claude     │     │  MCP        │     │  External   │
│  Desktop /  │────→│  Server     │────→│  Service    │
│  Claude Code│     │  (your app) │     │  (DB, API)  │
│  (MCP Client)     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘

The MCP Server exposes:
- Tools:     query_database, create_ticket, send_slack_message
- Resources: customer_data, product_catalog
- Prompts:   summarize_ticket, generate_report

Building a Simple MCP Server

The following is a minimal MCP server that exposes a database query tool:

from mcp.server import Server
from mcp.types import Tool, TextContent
import sqlite3
import json

server = Server("database-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="query_database",
            description="Run a read-only SQL query against the customer database.",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "SQL SELECT query"}
                },
                "required": ["query"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "query_database":
        conn = sqlite3.connect("customers.db")
        cursor = conn.cursor()

        if not arguments["query"].strip().upper().startswith("SELECT"):
            return [TextContent(type="text", text="Error: Only SELECT queries allowed")]

        cursor.execute(arguments["query"])
        columns = [d[0] for d in cursor.description]
        rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
        conn.close()

        return [TextContent(type="text", text=json.dumps(rows, indent=2))]

# Run with: python -m mcp.server.stdio database_server

Once this MCP server is running, any MCP-compatible client (Claude Code, Claude Desktop, or custom applications) can connect to it, and the AI model can query the underlying database through tool calling. The MCP protocol handles the communication.

MCP Compared with Other Approaches

MCP is gaining substantial adoption in 2026. Major IDE extensions, AI coding tools, and enterprise platforms are adopting it as the standard means of connecting AI systems to external systems. For developers building tools for AI models, implementing them as MCP servers helps future-proof the work.

Best Practices for Designing Tools

The quality of the tools directly determines how well an AI application performs. A well-designed tool is comparable to a well-written function: a clear name, documented parameters, predictable behaviour. A poorly designed tool produces hallucinated arguments, incorrect tool selection, and unsatisfactory user experiences.

Naming and Descriptions

The model reads the tool’s name and description to determine when and how to use it. Investment in these elements is worthwhile, since they function effectively as prompts for the model.

Key Design Principles

One tool per action. Avoid creating a single manage_database tool that can query, insert, update, and delete. Instead, create separate tools: query_database, insert_record, update_record, delete_record. This provides the model with clearer choices and reduces errors.

Detailed JSON Schema. Use types, required fields, enums, defaults, and descriptions for every parameter. The more constrained the schema, the more reliable the model’s output:

{
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"],
      "description": "Task priority level. Use 'critical' only for production outages.",
      "default": "medium"
    },
    "due_date": {
      "type": "string",
      "description": "Due date in ISO 8601 format (YYYY-MM-DD), e.g. '2026-04-15'"
    }
  }
}

Structured error messages. When a tool fails, return a structured error message that the model can understand and act on, rather than a stack trace:

# Bad: raises exception that crashes the loop
raise Exception("Connection timeout")

# Good: returns error the model can understand
return {"error": "Database connection timed out after 30s. The database may be under heavy load. Try again in a few minutes."}

Separate read and write tools. This separation is essential for safety. A query_database tool (read-only) is safe to call freely. A delete_record tool (destructive) should require confirmation. Separation allows different safety policies to be applied to each.

Confirmation for dangerous actions. Before deleting data, sending emails, or making payments, the model should ask for user confirmation. This can be implemented by having the tool return a “confirmation required” response that the model must present to the user before proceeding.

Common Pitfalls and How to Avoid Them

Even with well-designed tools, problems can arise. The following are the most common issues, along with their remedies:

Security Considerations

Security warrants particular attention because tool calling enables an LLM to take real actions. A prompt injection attack that convinces the model to call delete_all_users() is no longer a theoretical concern; it is a real risk.

Key security practices include:

1. Input validation. Validate all tool arguments before execution. The model should not be trusted to provide safe inputs consistently.
2. Least privilege. Provide tools with the minimum permissions necessary. Database tools should use read-only credentials unless writes are required.
3. Rate limiting. Limit how often tools can be called to prevent abuse or runaway loops.
4. Audit logging. Log every tool call with its arguments and results. This is essential for debugging and security audit.
5. Sandboxing. Code execution tools must run in isolated environments (containers, VMs, or WebAssembly sandboxes).
6. Confirmation gates. Destructive operations (delete, send, pay) should require human confirmation before execution.

Tool Calling in Production

Moving from a prototype to production requires additional engineering around reliability, observability, and cost management.

Reliability Patterns

Caching: Cache tool results to avoid redundant API calls. If the model requests the weather in Tokyo twice in the same conversation, the cached result should be returned. Use time-based expiration (for example, a 5-minute TTL for weather data).

from functools import lru_cache
from datetime import datetime, timedelta

_cache = {}

def cached_tool_call(name: str, args: dict, ttl_seconds: int = 300):
    key = f"{name}:{json.dumps(args, sort_keys=True)}"
    if key in _cache:
        result, timestamp = _cache[key]
        if datetime.now() - timestamp < timedelta(seconds=ttl_seconds):
            return result

    result = execute_tool(name, args)
    _cache[key] = (result, datetime.now())
    return result

Retry with backoff: External APIs fail. Implement retries with exponential backoff for transient errors (timeouts, rate limits, 5xx errors).

Fallback strategies: When a tool fails after retries, return a structured error message that allows the model to inform the user appropriately, rather than crashing the entire interaction.

Observability

Logging: Log every tool call in a structured format:

{
  "timestamp": "2026-04-03T10:30:00Z",
  "conversation_id": "conv_abc123",
  "tool_name": "get_weather",
  "arguments": {"city": "Tokyo"},
  "result_summary": "success, temperature=22",
  "latency_ms": 245,
  "tokens_used": {"input": 150, "output": 45}
}

Monitoring: Track key metrics:

• Tool call success rate (should remain above 95%).
• Average tool latency (directly affects user experience).
• Tool calls per conversation (indicative of complexity).
• Token cost per tool call cycle (each call adds tokens to the context).
• Error rates by tool (useful for identifying problematic tools).

Cost Optimisation

Every tool call adds tokens to the context window. The tool definitions themselves are included in every API request, so 20 detailed tools may add 2,000 to 3,000 tokens before the conversation begins.

Strategies to manage costs include:

• Dynamic tool loading. Include only relevant tools, based on the conversation context. A weather conversation does not require database tools.
• Result compression. Truncate or summarise large tool results before returning them to the model. A full database dump is rarely necessary; summary statistics are usually sufficient.
• Conversation pruning. In long multi-tool conversations, summarise earlier tool results and remove the raw data from the context.
• Model selection. Use cheaper, faster models (such as Claude Haiku or GPT-4o-mini) for simple tool-calling tasks, and reserve expensive models for complex reasoning.

Testing Tool-Calling Applications

Tools should be tested independently before they are integrated with the LLM:

1. Unit tests. Test each tool function with a variety of inputs, including edge cases and invalid arguments.
2. Integration tests. Test the tool against the actual API or database to which it connects.
3. LLM integration tests. Test the full loop with the model. Provide a set of test prompts and verify that the model calls the correct tools with correct arguments.
4. Adversarial tests. Test with prompts designed to trick the model into misusing tools (prompt injection).

# Example: testing that the model calls the right tool
def test_weather_tool_selection():
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        tools=tools,
        messages=[{"role": "user", "content": "What's the weather in London?"}]
    )

    tool_calls = [b for b in response.content if b.type == "tool_use"]
    assert len(tool_calls) == 1
    assert tool_calls[0].name == "get_weather"
    assert tool_calls[0].input["city"] == "London"

def test_no_tool_for_general_question():
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        tools=tools,
        messages=[{"role": "user", "content": "What is the capital of France?"}]
    )

    # Model should answer directly, no tool call
    assert response.stop_reason == "end_turn"

The Future of Tool Calling

Tool calling is evolving rapidly. Several directions are notable:

Computer Use

Anthropic's computer use capability extends tool calling to its logical conclusion: instead of calling specific APIs, the model controls an entire computer desktop. It views the screen (via screenshots), moves the mouse, clicks buttons, and types text. The "tools" become the entire computer interface: every application, website, and file. This is the most general form of tool use: rather than building a specific tool for every task, the model is given the same tools a human uses.

More Reliable Structured Output

Constrained decoding is making tool calling more reliable. Rather than relying on the model to produce valid JSON, the decoding process itself enforces the JSON Schema; the model is mechanically prevented from producing invalid output. OpenAI's strict mode and Anthropic's improvements in JSON reliability move in this direction.

Tool Learning and Discovery

Current models use tools that are explicitly defined in the request. Future models may be able to discover tools dynamically—browsing an API directory, reading documentation, and determining how to use a new tool without it being predefined. MCP is laying the groundwork for this through its discovery protocol.

Multi-Agent Tool Sharing

As multi-agent systems become more common (multiple AI agents collaborating on a task), tool sharing becomes important. One agent may specialise in database queries while another handles email. MCP's architecture supports this by allowing multiple agents to connect to the same tool servers.

Standardisation

MCP adoption is accelerating. In the same way that REST APIs standardised web service communication, MCP is standardising how AI models interact with external tools. For developers and companies building AI tools, this means writing the tool once and making it available to every AI model and client that supports MCP.

Final Thoughts

Tool calling is the underlying infrastructure behind every AI agent, every chatbot plugin, and every autonomous AI system. The mechanism is deceptively simple—a model outputs a function name and arguments, the application's code executes the function, and the result is returned to the model—but this simple loop is what transformed LLMs from text generators into systems that can act in the real world.

To summarise the material covered:

• The core concept. Tool calling allows LLMs to request the execution of external functions. The model plans; the application acts.
• The three-step loop. The user asks, the model calls a tool, the application executes the tool, and the model responds with the result.
• Provider implementations. Claude, GPT, and Gemini all support tool calling with slightly different formats but the same underlying pattern.
• Practical patterns. Examples range from simple weather lookups to chained tool calls, database queries, and multi-tool agents.
• The agentic loop. Tool calling in a loop is the foundation of AI agents. Claude Code, ChatGPT plugins, and GitHub Copilot all operate on this basis.
• MCP. The open standard that is making tool definitions universal and interoperable.
• Best practices. Clear naming, detailed schemas, error handling, security, and the read/write separation principle.
• Production concerns. Caching, logging, cost optimisation, and testing strategies.

Developers should begin building with tool calling immediately. Select an API already in use, define it as a tool, and connect it to Claude or GPT. The transition from "AI that converses" to "AI that acts" is more rapid than expected. For analysts and investors, the relevant observation is that tool calling is not merely a feature; it is the foundation of the entire AI agent ecosystem. Companies that master tool integration will define the next phase of AI.

The era of AI that only converses has passed. The era of AI that acts is beginning, and tool calling is the mechanism that makes it possible.

References

1. Anthropic. "Tool use (function calling)—Claude Documentation." docs.anthropic.com/en/docs/build-with-claude/tool-use
2. OpenAI. "Function calling, OpenAI API Documentation." platform.openai.com/docs/guides/function-calling
3. Google. "Function calling—Gemini API Documentation." ai.google.dev/gemini-api/docs/function-calling
4. Anthropic. "Model Context Protocol—Documentation." modelcontextprotocol.io
5. Anthropic. "Computer use, Claude Documentation." docs.anthropic.com/en/docs/build-with-claude/computer-use
6. Anthropic. "Claude Code—Documentation." docs.anthropic.com/en/docs/claude-code
7. Schick, T., et al. "Toolformer: Language Models Can Teach Themselves to Use Tools." arXiv:2302.04761, 2023.
8. Qin, Y., et al. "ToolLLM: Facilitating Large Language Models to Master 16000+ Real-world APIs." arXiv:2307.16789, 2023.

Consider a scenario in which a developer is commuting home on a train after a long day. The developer opens Telegram on a phone and types /deploy staging. Within two minutes, Claude Code on the development machine activates, runs the entire deployment pipeline, and returns a confirmation message with the deployment URL—all from the phone, without any need to open a laptop. The capability described is neither speculative nor difficult to assemble. It can be implemented in a single afternoon using nothing more than a free messaging bot and a short Python script.

The setup tends to alter the way developers think about their workflows. Claude Code ceases to be a tool that is usable only while seated at a desk and instead becomes a continuously available assistant accessible from anywhere—a grocery store, a gym, or a coffee shop in another city. The implementation is also remarkably simple.

This guide describes the construction of complete, production-ready bridges between Claude Code and the most widely used messaging platforms: Telegram, Slack, Discord, and a generic webhook approach that is compatible with most other systems. Full Python scripts, systemd service files, Docker configurations, and production-proven security practices are provided. By the end, a remote control for Claude Code that fits in a pocket is fully assembled.

Why Remote Control Claude Code?

Before implementation details are considered, the motivation for remote control deserves examination. Claude Code is an exceptionally capable tool, yet by default it is tethered to the terminal. The user must be at the machine, in the shell, and actively observing the output. That constraint eliminates a large number of practical use cases.

The Case for Remote Access

Work from anywhere. Builds, deployments, code generation, and analysis can be triggered from a phone. A laptop is not required. In fact, no computer is required. Any device capable of sending a text message becomes a development terminal.

Asynchronous workflows. Complex tasks—refactoring a module, writing tests for an entire package, or producing a comprehensive code review—can be dispatched to Claude Code, after which the developer can attend to other matters. A notification arrives once the work is complete, removing the need to wait at a terminal.

Team collaboration. When the bot is added to a shared Slack channel, any member of the engineering team can trigger shared workflows. A junior developer can run the deployment pipeline without SSH access to the server. A product manager can produce the daily status report without delegating the task.

Emergency fixes. If production fails while a developer is at the airport, there is no need to find a quiet corner, open a laptop, and tether to a phone hotspot. The command /run fix the null pointer in src/auth.py and deploy to production can be issued directly from the Slack app on the phone.

Monitoring and response. Proactive alerts can be configured so that, when a CI/CD pipeline fails, a Telegram notification is dispatched together with a one-tap command for retry or investigation. Similarly, a Slack alert with an action button to restart the service can accompany degraded server health.

Platform Comparison

Not all messaging platforms are equally well suited to this use case. The principal options are compared below:

Architecture Overview

Regardless of the messaging platform selected, the architecture follows the same pattern. The pattern is the key to the system, and once it is understood the same approach can be adapted to any platform within minutes.

The Message Flow

The complete flow from the phone to Claude Code and back is illustrated below:

┌──────────┐    ┌───────────────┐    ┌──────────────┐    ┌─────────────┐
│  Your    │───▶│   Messaging   │───▶│   Bridge     │───▶│  Claude     │
│  Phone   │    │   Platform    │    │   Server     │    │  Code CLI   │
│          │◀───│   (Telegram)  │◀───│   (Python)   │◀───│  (claude)   │
└──────────┘    └───────────────┘    └──────────────┘    └─────────────┘
                                           │
                                     ┌─────┴─────┐
                                     │  Auth     │
                                     │  Rate     │
                                     │  Limit    │
                                     │  Logging  │
                                     └───────────┘

The central component is the bridge server, a lightweight Python or Node.js application that performs three functions:

1. Receives messages from the messaging platform’s bot API, either via polling or webhooks.
2. Validates and routes messages through security checks, including authentication, rate limiting, and command allowlisting.
3. Executes Claude Code as a subprocess and returns the result to the chat.

The bridge server runs on the same machine on which Claude Code is installed. If Claude Code is on the local development machine, the bridge runs there as well. For a more robust configuration, the bridge may be hosted on a VPS and may use SSH to invoke Claude Code on the development machine; the simplest version is described first.

Why a Bridge Server?

The question of why the messaging platform is not connected directly to Claude Code naturally arises. The reason is that Claude Code is a CLI tool that reads from stdin and writes to stdout. It does not natively speak HTTP or WebSocket protocols. The bridge translates between the messaging platform’s API protocol and Claude Code’s command-line interface and may be viewed as a thin adapter layer.

Running Claude Code Non-Interactively

Before any bot is constructed, it is necessary to understand how to run Claude Code without an interactive terminal. This foundation underpins every bridge server.

The Print Flag

The most important flag is -p (or --print). This flag runs Claude Code in non-interactive mode: a prompt is supplied, processed, the result is printed, and the process exits. There is no interactive UI, no REPL, and no terminal manipulation.

# Basic non-interactive usage
claude -p "List all Python files in the current directory"

# With a specific working directory
cd /path/to/project && claude -p "Explain the architecture of this project"

# JSON output for structured parsing
claude -p "List all functions in src/main.py" --output-format json

Key CLI Flags for Non-Interactive Use

Calling Claude Code from Python

The following function is the core that every bridge server relies upon and the heart of the entire system:

import subprocess
import os

def run_claude(prompt: str, working_dir: str = None, timeout: int = 300) -> dict:
    """
    Run Claude Code non-interactively and return the result.

    Args:
        prompt: The prompt to send to Claude Code
        working_dir: Directory to run in (uses CLAUDE_WORK_DIR env var as default)
        timeout: Maximum seconds to wait (default 5 minutes)

    Returns:
        dict with 'success' (bool), 'output' (str), and 'error' (str)
    """
    work_dir = working_dir or os.getenv("CLAUDE_WORK_DIR", os.path.expanduser("~"))

    try:
        result = subprocess.run(
            ["claude", "-p", prompt],
            capture_output=True,
            text=True,
            timeout=timeout,
            cwd=work_dir,
            env={**os.environ, "TERM": "dumb"}  # Prevent terminal escape codes
        )

        if result.returncode == 0:
            return {
                "success": True,
                "output": result.stdout.strip(),
                "error": None
            }
        else:
            return {
                "success": False,
                "output": result.stdout.strip(),
                "error": result.stderr.strip()
            }

    except subprocess.TimeoutExpired:
        return {
            "success": False,
            "output": None,
            "error": f"Command timed out after {timeout} seconds"
        }
    except FileNotFoundError:
        return {
            "success": False,
            "output": None,
            "error": "Claude Code CLI not found. Is it installed and in PATH?"
        }
    except Exception as e:
        return {
            "success": False,
            "output": None,
            "error": str(e)
        }

Handling Long-Running Tasks

Some Claude Code tasks may run for several minutes, including refactoring large files, executing full test suites, or generating comprehensive documentation. Such cases must be handled gracefully:

import asyncio
import subprocess
from concurrent.futures import ThreadPoolExecutor

executor = ThreadPoolExecutor(max_workers=3)

async def run_claude_async(prompt: str, working_dir: str = None, timeout: int = 600):
    """Run Claude Code in a thread pool to avoid blocking the bot's event loop."""
    loop = asyncio.get_event_loop()
    return await loop.run_in_executor(
        executor,
        lambda: run_claude(prompt, working_dir, timeout)
    )

The pattern shown above is essential. Messaging bot libraries such as python-telegram-bot and slack-bolt run on asynchronous event loops. A direct call to subprocess.run blocks the entire bot, so that no other messages can be processed while Claude Code is running. Executing the subprocess in a thread pool executor keeps the bot responsive.

Method 1: Telegram Bot — Complete Implementation

Telegram is the optimal starting point. Its bot API is free, unlimited, requires no server because it supports polling, and the mobile app is well designed. A working remote control can be assembled from scratch in approximately fifteen minutes.

Step 1: Create a Telegram Bot

Open Telegram on the phone or desktop and search for @BotFather, the official Telegram bot for creating and managing bots. Begin a conversation and proceed as follows:

1. Send /newbot.
2. Enter a display name for the bot (for example, “My Claude Code Bot”).
3. Enter a username, which must end in “bot” (for example, “my_claude_code_bot”).
4. BotFather will respond with an API token, which must be stored securely.

Next, the bot’s command menu should be configured so that autocomplete is available in the chat:

# Send this to @BotFather:
/setcommands

# Then select your bot and paste:
run - Run a Claude Code prompt
deploy - Deploy to an environment
test - Run project tests
status - Check current task status
git - Run git commands (log, status, diff)
help - List available commands

Finally, the Telegram user ID is required for authentication. A message sent to @userinfobot will be answered with the numeric user ID. This value should be stored and ensures that only the authorised user can control the bot.

Step 2: Build the Bridge Server

The following is a complete, production-ready Telegram bridge server. It is not an illustrative fragment: authentication, rate limiting, asynchronous execution, output truncation, and proper error handling are all included:

#!/usr/bin/env python3
"""
Telegram Bridge for Claude Code
================================
Controls Claude Code sessions from Telegram messages.

Usage:
    python telegram_bridge.py

Environment variables (in .env):
    TELEGRAM_BOT_TOKEN    - Bot token from @BotFather
    TELEGRAM_ALLOWED_USERS - Comma-separated list of allowed user IDs
    CLAUDE_WORK_DIR       - Working directory for Claude Code
"""

import asyncio
import logging
import os
import subprocess
import time
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime
from functools import wraps

from dotenv import load_dotenv
from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)

load_dotenv()

# --- Configuration ---
BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
ALLOWED_USERS = set(
    int(uid.strip())
    for uid in os.getenv("TELEGRAM_ALLOWED_USERS", "").split(",")
    if uid.strip()
)
WORK_DIR = os.getenv("CLAUDE_WORK_DIR", os.path.expanduser("~/projects"))
MAX_MESSAGE_LENGTH = 4000  # Telegram limit is 4096, leave margin
RATE_LIMIT = 10  # Max commands per hour per user
COMMAND_TIMEOUT = 600  # 10 minutes max per command

# --- Logging ---
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    level=logging.INFO,
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler("telegram_bridge.log"),
    ],
)
logger = logging.getLogger(__name__)

# --- State ---
executor = ThreadPoolExecutor(max_workers=3)
rate_limits = defaultdict(list)  # user_id -> list of timestamps
active_tasks = {}  # user_id -> task description


# --- Helpers ---

def run_claude(prompt: str, working_dir: str = None, timeout: int = COMMAND_TIMEOUT) -> dict:
    """Run Claude Code non-interactively."""
    work_dir = working_dir or WORK_DIR
    try:
        result = subprocess.run(
            ["claude", "-p", prompt],
            capture_output=True,
            text=True,
            timeout=timeout,
            cwd=work_dir,
            env={**os.environ, "TERM": "dumb"},
        )
        return {
            "success": result.returncode == 0,
            "output": result.stdout.strip(),
            "error": result.stderr.strip() if result.returncode != 0 else None,
        }
    except subprocess.TimeoutExpired:
        return {"success": False, "output": None, "error": f"Timed out after {timeout}s"}
    except FileNotFoundError:
        return {"success": False, "output": None, "error": "Claude CLI not found in PATH"}
    except Exception as e:
        return {"success": False, "output": None, "error": str(e)}


def check_rate_limit(user_id: int) -> bool:
    """Return True if user is within rate limits."""
    now = time.time()
    hour_ago = now - 3600
    rate_limits[user_id] = [t for t in rate_limits[user_id] if t > hour_ago]
    if len(rate_limits[user_id]) >= RATE_LIMIT:
        return False
    rate_limits[user_id].append(now)
    return True


def truncate_output(text: str, max_len: int = MAX_MESSAGE_LENGTH) -> str:
    """Truncate output to fit Telegram's message limit."""
    if not text or len(text) <= max_len:
        return text
    return text[: max_len - 100] + f"\n\n... (truncated, {len(text)} chars total)"


def auth_required(func):
    """Decorator to restrict commands to allowed users."""
    @wraps(func)
    async def wrapper(update: Update, context: ContextTypes.DEFAULT_TYPE):
        user_id = update.effective_user.id
        if ALLOWED_USERS and user_id not in ALLOWED_USERS:
            logger.warning(f"Unauthorized access attempt by user {user_id}")
            await update.message.reply_text("Unauthorized. Your user ID is not in the allow list.")
            return
        if not check_rate_limit(user_id):
            await update.message.reply_text(
                f"Rate limit exceeded. Max {RATE_LIMIT} commands per hour."
            )
            return
        return await func(update, context)
    return wrapper


# --- Command Handlers ---

@auth_required
async def cmd_run(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Run an arbitrary Claude Code prompt."""
    if not context.args:
        await update.message.reply_text("Usage: /run \nExample: /run list all Python files")
        return

    prompt = " ".join(context.args)
    user_id = update.effective_user.id
    logger.info(f"User {user_id} running: {prompt}")

    status_msg = await update.message.reply_text("Working on it...")
    active_tasks[user_id] = prompt

    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    del active_tasks[user_id]

    if result["success"]:
        output = truncate_output(result["output"]) or "(no output)"
        await status_msg.edit_text(f"Done:\n\n{output}")
    else:
        error = result["error"] or "Unknown error"
        await status_msg.edit_text(f"Failed:\n\n{error}")


@auth_required
async def cmd_deploy(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Trigger a deployment."""
    env = context.args[0] if context.args else "staging"
    allowed_envs = ["staging", "production", "dev"]

    if env not in allowed_envs:
        await update.message.reply_text(f"Invalid environment. Choose from: {', '.join(allowed_envs)}")
        return

    if env == "production":
        await update.message.reply_text(
            "You requested a PRODUCTION deployment. Send /confirm-deploy to proceed."
        )
        context.user_data["pending_deploy"] = "production"
        return

    status_msg = await update.message.reply_text(f"Deploying to {env}...")

    prompt = f"Run the deployment pipeline for the {env} environment. Show the deployment URL when done."
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = truncate_output(result["output"]) if result["success"] else result["error"]
    emoji = "deployed" if result["success"] else "failed"
    await status_msg.edit_text(f"Deployment {emoji}:\n\n{output}")


@auth_required
async def cmd_confirm_deploy(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Confirm a pending production deployment."""
    pending = context.user_data.get("pending_deploy")
    if pending != "production":
        await update.message.reply_text("No pending deployment to confirm.")
        return

    del context.user_data["pending_deploy"]
    status_msg = await update.message.reply_text("Deploying to PRODUCTION...")

    prompt = "Run the deployment pipeline for the production environment. Show the deployment URL and run health checks."
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = truncate_output(result["output"]) if result["success"] else result["error"]
    await status_msg.edit_text(f"Production deployment result:\n\n{output}")


@auth_required
async def cmd_test(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Run project tests."""
    status_msg = await update.message.reply_text("Running tests...")

    prompt = "Run the project's test suite and report results. Show passed, failed, and error counts."
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = truncate_output(result["output"]) if result["success"] else result["error"]
    await status_msg.edit_text(f"Test results:\n\n{output}")


@auth_required
async def cmd_git(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Run git commands (read-only for safety)."""
    if not context.args:
        await update.message.reply_text("Usage: /git \nExamples: /git status, /git log --oneline -10")
        return

    git_cmd = " ".join(context.args)
    safe_commands = ["status", "log", "diff", "branch", "show", "remote", "tag"]
    first_word = git_cmd.split()[0] if git_cmd.split() else ""

    if first_word not in safe_commands:
        await update.message.reply_text(
            f"Only read-only git commands are allowed: {', '.join(safe_commands)}"
        )
        return

    prompt = f"Run this git command and show the output: git {git_cmd}"
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = truncate_output(result["output"]) if result["success"] else result["error"]
    await update.message.reply_text(f"git {git_cmd}:\n\n{output}")


@auth_required
async def cmd_status(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Show currently active tasks."""
    if not active_tasks:
        await update.message.reply_text("No active tasks.")
        return

    lines = [f"User {uid}: {task}" for uid, task in active_tasks.items()]
    await update.message.reply_text("Active tasks:\n\n" + "\n".join(lines))


async def cmd_help(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Show available commands."""
    help_text = """Available commands:

/run  - Run any Claude Code prompt
/deploy  - Deploy (staging/production/dev)
/test - Run project tests
/git  - Run read-only git commands
/status - Show active tasks
/help - Show this message

Examples:
/run fix the TypeError in src/auth.py
/deploy staging
/git log --oneline -5
/run write tests for src/utils.py"""
    await update.message.reply_text(help_text)


# --- Main ---

def main():
    if not BOT_TOKEN:
        logger.error("TELEGRAM_BOT_TOKEN not set in .env")
        return

    if not ALLOWED_USERS:
        logger.warning("TELEGRAM_ALLOWED_USERS not set — bot is open to everyone!")

    app = Application.builder().token(BOT_TOKEN).build()

    app.add_handler(CommandHandler("run", cmd_run))
    app.add_handler(CommandHandler("deploy", cmd_deploy))
    app.add_handler(CommandHandler("confirm_deploy", cmd_confirm_deploy))
    app.add_handler(CommandHandler("test", cmd_test))
    app.add_handler(CommandHandler("git", cmd_git))
    app.add_handler(CommandHandler("status", cmd_status))
    app.add_handler(CommandHandler("help", cmd_help))
    app.add_handler(CommandHandler("start", cmd_help))

    logger.info("Telegram bridge started. Polling for messages...")
    app.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

Step 3: Configuration

A .env file for the bridge server should be created:

# .env for Telegram bridge
TELEGRAM_BOT_TOKEN=7123456789:AAH-your-token-here
TELEGRAM_ALLOWED_USERS=123456789,987654321
CLAUDE_WORK_DIR=/home/youruser/projects/myapp

A requirements.txt file is also required:

python-telegram-bot>=21.0
python-dotenv>=1.0.0

The dependencies are then installed and the bridge launched:

pip install -r requirements.txt
python telegram_bridge.py

Step 4: Test It

Open Telegram on the phone and send a message to the bot:

/run list all Python files in the project and count them

The reply “Working on it…” should appear, followed by the actual output within approximately a minute. If a failure occurs, the telegram_bridge.log file should be examined for error details.

Common Issues and Debugging

Bot does not respond: Verify that the TELEGRAM_BOT_TOKEN is correct. Send /start; if no response is received, either the token is incorrect or the bot process is not running.

“Unauthorized” error: The Telegram user ID is not present in TELEGRAM_ALLOWED_USERS. The ID should be verified via @userinfobot.

Claude command times out: The default timeout is 10 minutes. For very long tasks, COMMAND_TIMEOUT should be increased. The Claude Code authentication state should also be confirmed by running claude in the terminal beforehand.

Garbled output: The TERM=dumb setting must be present in the subprocess environment, otherwise Claude Code may emit ANSI escape codes.

Method 2: Slack Bot — Complete Implementation

Slack is the natural choice for team environments. Its bot platform is more complex than Telegram’s, but offers richer features including threads, file uploads, interactive buttons, and integration with other workplace tools.

Step 1: Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name it (e.g., “Claude Code Bot”) and select your workspace
4. Under OAuth & Permissions, add these Bot Token Scopes:
   • chat:write — send messages
   • commands — handle slash commands
   • files:write — upload files (for long output)
   • app_mentions:read — respond to @mentions
5. Under Socket Mode, enable it and create an app-level token (needed for local development without a public URL)
6. Under Slash Commands, create a command called /claude
7. Install the app to your workspace
8. Copy the Bot User OAuth Token (starts with xoxb-) and the App-Level Token (starts with xapp-)

Step 2: Build the Slack Bridge

#!/usr/bin/env python3
"""
Slack Bridge for Claude Code
==============================
Controls Claude Code sessions via Slack slash commands and mentions.

Usage:
    python slack_bridge.py

Environment variables (in .env):
    SLACK_BOT_TOKEN     - Bot User OAuth Token (xoxb-...)
    SLACK_APP_TOKEN     - App-Level Token for Socket Mode (xapp-...)
    SLACK_ALLOWED_CHANNELS - Comma-separated channel IDs (optional)
    CLAUDE_WORK_DIR     - Working directory for Claude Code
"""

import asyncio
import logging
import os
import subprocess
import tempfile
import time
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor

from dotenv import load_dotenv
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

load_dotenv()

# --- Configuration ---
BOT_TOKEN = os.getenv("SLACK_BOT_TOKEN")
APP_TOKEN = os.getenv("SLACK_APP_TOKEN")
ALLOWED_CHANNELS = set(
    ch.strip()
    for ch in os.getenv("SLACK_ALLOWED_CHANNELS", "").split(",")
    if ch.strip()
)
WORK_DIR = os.getenv("CLAUDE_WORK_DIR", os.path.expanduser("~/projects"))
RATE_LIMIT = 10
COMMAND_TIMEOUT = 600
MAX_SLACK_LENGTH = 3900  # Leave margin under Slack's 4000-char block limit

# --- Logging ---
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    level=logging.INFO,
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler("slack_bridge.log"),
    ],
)
logger = logging.getLogger(__name__)

# --- State ---
executor = ThreadPoolExecutor(max_workers=3)
rate_limits = defaultdict(list)
app = App(token=BOT_TOKEN)


def run_claude(prompt: str, working_dir: str = None, timeout: int = COMMAND_TIMEOUT) -> dict:
    """Run Claude Code non-interactively."""
    work_dir = working_dir or WORK_DIR
    try:
        result = subprocess.run(
            ["claude", "-p", prompt],
            capture_output=True,
            text=True,
            timeout=timeout,
            cwd=work_dir,
            env={**os.environ, "TERM": "dumb"},
        )
        return {
            "success": result.returncode == 0,
            "output": result.stdout.strip(),
            "error": result.stderr.strip() if result.returncode != 0 else None,
        }
    except subprocess.TimeoutExpired:
        return {"success": False, "output": None, "error": f"Timed out after {timeout}s"}
    except Exception as e:
        return {"success": False, "output": None, "error": str(e)}


def check_rate_limit(user_id: str) -> bool:
    now = time.time()
    hour_ago = now - 3600
    rate_limits[user_id] = [t for t in rate_limits[user_id] if t > hour_ago]
    if len(rate_limits[user_id]) >= RATE_LIMIT:
        return False
    rate_limits[user_id].append(now)
    return True


def upload_as_file(client, channel: str, thread_ts: str, content: str, filename: str):
    """Upload long output as a file snippet."""
    with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
        f.write(content)
        f.flush()
        client.files_upload_v2(
            channel=channel,
            thread_ts=thread_ts,
            file=f.name,
            filename=filename,
            title="Claude Code Output",
        )
    os.unlink(f.name)


@app.command("/claude")
def handle_claude_command(ack, say, command, client):
    """Handle /claude slash commands."""
    ack()  # Acknowledge within 3 seconds

    user_id = command["user_id"]
    channel_id = command["channel_id"]
    text = command.get("text", "").strip()

    # Channel restriction
    if ALLOWED_CHANNELS and channel_id not in ALLOWED_CHANNELS:
        say(f"This command is not allowed in this channel.", ephemeral=True)
        return

    # Rate limiting
    if not check_rate_limit(user_id):
        say(f"Rate limit exceeded. Max {RATE_LIMIT} commands per hour.")
        return

    if not text:
        say(
            "Usage: `/claude  `\n"
            "Actions: `run`, `deploy`, `test`, `git`, `status`\n"
            "Example: `/claude run list all Python files`"
        )
        return

    parts = text.split(maxsplit=1)
    action = parts[0].lower()
    args = parts[1] if len(parts) > 1 else ""

    logger.info(f"User {user_id} in {channel_id}: /claude {action} {args}")

    # Send initial "working" message in a thread
    response = client.chat_postMessage(
        channel=channel_id,
        text=f"Working on: `{action} {args}`...",
    )
    thread_ts = response["ts"]

    # Add reaction to show we're working
    client.reactions_add(channel=channel_id, timestamp=thread_ts, name="hourglass_flowing_sand")

    # Route command
    if action == "run":
        prompt = args or "Show project status"
    elif action == "deploy":
        env = args or "staging"
        prompt = f"Run the deployment pipeline for the {env} environment."
    elif action == "test":
        prompt = "Run the project test suite and report results."
    elif action == "git":
        safe = ["status", "log", "diff", "branch", "show"]
        first = args.split()[0] if args else ""
        if first not in safe:
            client.chat_postMessage(
                channel=channel_id, thread_ts=thread_ts,
                text=f"Only these git commands are allowed: {', '.join(safe)}",
            )
            return
        prompt = f"Run this git command and show the output: git {args}"
    else:
        prompt = text  # Treat the whole thing as a prompt

    # Execute in thread pool
    import concurrent.futures
    future = executor.submit(run_claude, prompt)
    try:
        result = future.result(timeout=COMMAND_TIMEOUT + 30)
    except concurrent.futures.TimeoutError:
        result = {"success": False, "output": None, "error": "Execution timed out"}

    # Remove working reaction, add result reaction
    try:
        client.reactions_remove(channel=channel_id, timestamp=thread_ts, name="hourglass_flowing_sand")
    except Exception:
        pass

    if result["success"]:
        client.reactions_add(channel=channel_id, timestamp=thread_ts, name="white_check_mark")
        output = result["output"] or "(no output)"

        if len(output) > MAX_SLACK_LENGTH:
            # Upload as file for long output
            client.chat_postMessage(
                channel=channel_id, thread_ts=thread_ts,
                text="Output is too long for a message. Uploading as file...",
            )
            upload_as_file(client, channel_id, thread_ts, output, "claude_output.txt")
        else:
            client.chat_postMessage(
                channel=channel_id, thread_ts=thread_ts,
                text=f"```\n{output}\n```",
            )
    else:
        client.reactions_add(channel=channel_id, timestamp=thread_ts, name="x")
        error = result["error"] or "Unknown error"
        client.chat_postMessage(
            channel=channel_id, thread_ts=thread_ts,
            text=f"Failed:\n```\n{error}\n```",
        )


@app.event("app_mention")
def handle_mention(event, say, client):
    """Handle @bot mentions in channels."""
    text = event.get("text", "")
    # Strip the bot mention to get just the prompt
    # Mentions look like <@U12345> prompt here
    import re
    prompt = re.sub(r"<@\w+>\s*", "", text).strip()

    if not prompt:
        say("Mention me with a prompt! Example: `@Claude Code Bot list Python files`", thread_ts=event["ts"])
        return

    say(f"Working on it...", thread_ts=event["ts"])

    import concurrent.futures
    future = executor.submit(run_claude, prompt)
    try:
        result = future.result(timeout=COMMAND_TIMEOUT + 30)
    except concurrent.futures.TimeoutError:
        result = {"success": False, "output": None, "error": "Timed out"}

    output = result["output"] if result["success"] else result["error"]
    say(f"```\n{output}\n```", thread_ts=event["ts"])


if __name__ == "__main__":
    if not BOT_TOKEN or not APP_TOKEN:
        logger.error("SLACK_BOT_TOKEN and SLACK_APP_TOKEN must be set in .env")
        exit(1)

    logger.info("Slack bridge starting in Socket Mode...")
    handler = SocketModeHandler(app, APP_TOKEN)
    handler.start()

The corresponding .env file:

# .env for Slack bridge
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-level-token
SLACK_ALLOWED_CHANNELS=C01ABCDEF,C02GHIJKL
CLAUDE_WORK_DIR=/home/youruser/projects/myapp

And requirements.txt:

slack-bolt>=1.18.0
python-dotenv>=1.0.0

Step 3: Advanced Slack Features

Slack’s Block Kit enables interactive messages with buttons. A confirmation dialog for deployments can be added as follows:

# Add this handler for interactive buttons
@app.action("approve_deploy")
def handle_approve(ack, body, client):
    ack()
    user = body["user"]["id"]
    channel = body["channel"]["id"]
    thread_ts = body["message"]["ts"]

    client.chat_postMessage(
        channel=channel, thread_ts=thread_ts,
        text=f"<@{user}> approved the deployment. Deploying now...",
    )

    result = run_claude("Deploy to production and run health checks.")
    output = result["output"] if result["success"] else result["error"]
    client.chat_postMessage(
        channel=channel, thread_ts=thread_ts,
        text=f"Deployment result:\n```\n{output}\n```",
    )


@app.action("reject_deploy")
def handle_reject(ack, body, client):
    ack()
    user = body["user"]["id"]
    channel = body["channel"]["id"]
    thread_ts = body["message"]["ts"]
    client.chat_postMessage(
        channel=channel, thread_ts=thread_ts,
        text=f"<@{user}> cancelled the deployment.",
    )

Thread-based responses keep the channel tidy. Every command response is posted as a thread reply to the initial “Working on it…” message, so the #engineering channel is not flooded with Claude Code output.

Method 3: Discord Bot

Discord is particularly well suited to open-source communities and hobby projects. The setup differs slightly from Telegram and Slack but follows the same bridge pattern.

Create a Discord Bot

1. Go to discord.com/developers/applications
2. Click New Application, name it, and create it
3. Go to Bot → click Add Bot
4. Copy the Bot Token
5. Under Privileged Gateway Intents, enable Message Content Intent
6. Go to OAuth2 → URL Generator, select scopes bot and applications.commands, and permissions Send Messages, Read Message History, Attach Files
7. Use the generated URL to invite the bot to your server

Discord Bridge Server

#!/usr/bin/env python3
"""
Discord Bridge for Claude Code
================================
Controls Claude Code sessions via Discord slash commands.
"""

import asyncio
import logging
import os
import subprocess
from concurrent.futures import ThreadPoolExecutor

import discord
from discord import app_commands
from dotenv import load_dotenv

load_dotenv()

BOT_TOKEN = os.getenv("DISCORD_BOT_TOKEN")
ALLOWED_ROLES = os.getenv("DISCORD_ALLOWED_ROLES", "").split(",")  # Role names
WORK_DIR = os.getenv("CLAUDE_WORK_DIR", os.path.expanduser("~/projects"))
COMMAND_TIMEOUT = 600

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
executor = ThreadPoolExecutor(max_workers=3)


def run_claude(prompt: str, timeout: int = COMMAND_TIMEOUT) -> dict:
    try:
        result = subprocess.run(
            ["claude", "-p", prompt],
            capture_output=True, text=True, timeout=timeout,
            cwd=WORK_DIR, env={**os.environ, "TERM": "dumb"},
        )
        return {
            "success": result.returncode == 0,
            "output": result.stdout.strip(),
            "error": result.stderr.strip() if result.returncode != 0 else None,
        }
    except subprocess.TimeoutExpired:
        return {"success": False, "output": None, "error": f"Timed out after {timeout}s"}
    except Exception as e:
        return {"success": False, "output": None, "error": str(e)}


class ClaudeBot(discord.Client):
    def __init__(self):
        intents = discord.Intents.default()
        intents.message_content = True
        super().__init__(intents=intents)
        self.tree = app_commands.CommandTree(self)

    async def setup_hook(self):
        await self.tree.sync()
        logger.info("Slash commands synced.")


bot = ClaudeBot()


def has_permission(interaction: discord.Interaction) -> bool:
    if not ALLOWED_ROLES or ALLOWED_ROLES == [""]:
        return True
    user_roles = [r.name for r in interaction.user.roles] if hasattr(interaction.user, "roles") else []
    return any(role in ALLOWED_ROLES for role in user_roles)


@bot.tree.command(name="claude", description="Run a Claude Code prompt")
@app_commands.describe(prompt="The prompt to send to Claude Code")
async def claude_command(interaction: discord.Interaction, prompt: str):
    if not has_permission(interaction):
        await interaction.response.send_message("You do not have permission.", ephemeral=True)
        return

    await interaction.response.send_message(f"Working on: `{prompt}`...")

    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    if result["success"]:
        output = result["output"] or "(no output)"
        # Discord has a 2000 char limit
        if len(output) > 1900:
            # Send as file attachment
            with open("/tmp/claude_output.txt", "w") as f:
                f.write(output)
            await interaction.followup.send(
                "Output (see attached file):",
                file=discord.File("/tmp/claude_output.txt"),
            )
        else:
            await interaction.followup.send(f"```\n{output}\n```")
    else:
        await interaction.followup.send(f"Failed: {result['error']}")


@bot.tree.command(name="deploy", description="Deploy to an environment")
@app_commands.describe(environment="Target environment (staging/production)")
async def deploy_command(interaction: discord.Interaction, environment: str = "staging"):
    if not has_permission(interaction):
        await interaction.response.send_message("You do not have permission.", ephemeral=True)
        return

    await interaction.response.send_message(f"Deploying to {environment}...")

    prompt = f"Run the deployment pipeline for {environment}. Show the URL when done."
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = result["output"] if result["success"] else result["error"]
    await interaction.followup.send(f"Deploy result:\n```\n{output[:1900]}\n```")


@bot.tree.command(name="test", description="Run project tests")
async def test_command(interaction: discord.Interaction):
    if not has_permission(interaction):
        await interaction.response.send_message("You do not have permission.", ephemeral=True)
        return

    await interaction.response.send_message("Running tests...")
    prompt = "Run the test suite and report results."
    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(executor, lambda: run_claude(prompt))

    output = result["output"] if result["success"] else result["error"]
    if len(output) > 1900:
        with open("/tmp/test_output.txt", "w") as f:
            f.write(output)
        await interaction.followup.send("Test results:", file=discord.File("/tmp/test_output.txt"))
    else:
        await interaction.followup.send(f"```\n{output}\n```")


if __name__ == "__main__":
    if not BOT_TOKEN:
        logger.error("DISCORD_BOT_TOKEN not set")
        exit(1)
    bot.run(BOT_TOKEN)

Discord’s 2,000-character message limit is the most restrictive of all platforms covered. The bot accommodates this constraint by uploading long output automatically as a file attachment, a pattern that is advisable for any platform with tight limits.

Method 4: Generic Webhook Approach

Microsoft Teams, WhatsApp, LINE, and other platforms can be supported by building a generic webhook server that any platform can invoke, rather than writing a platform-specific bot. This is the most flexible approach.

FastAPI Webhook Server

#!/usr/bin/env python3
"""
Generic Webhook Bridge for Claude Code
========================================
A simple HTTP server that accepts webhook requests and runs Claude Code.
Works with any messaging platform that supports outgoing webhooks.

Usage:
    uvicorn webhook_bridge:app --host 0.0.0.0 --port 8080
"""

import asyncio
import hashlib
import hmac
import logging
import os
import subprocess
import time
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor

from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException, Header, Request
from pydantic import BaseModel

load_dotenv()

WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET", "change-me-to-a-random-string")
WORK_DIR = os.getenv("CLAUDE_WORK_DIR", os.path.expanduser("~/projects"))
COMMAND_TIMEOUT = 600
RATE_LIMIT = 10

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
executor = ThreadPoolExecutor(max_workers=3)
rate_limits = defaultdict(list)

app = FastAPI(title="Claude Code Webhook Bridge")


class CommandRequest(BaseModel):
    command: str
    working_dir: str | None = None
    timeout: int | None = None
    user_id: str | None = None


class CommandResponse(BaseModel):
    success: bool
    output: str | None
    error: str | None
    duration_seconds: float


def verify_signature(payload: bytes, signature: str) -> bool:
    """Verify HMAC-SHA256 webhook signature."""
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)


def run_claude(prompt: str, working_dir: str = None, timeout: int = COMMAND_TIMEOUT) -> dict:
    work_dir = working_dir or WORK_DIR
    try:
        result = subprocess.run(
            ["claude", "-p", prompt],
            capture_output=True, text=True, timeout=timeout,
            cwd=work_dir, env={**os.environ, "TERM": "dumb"},
        )
        return {
            "success": result.returncode == 0,
            "output": result.stdout.strip(),
            "error": result.stderr.strip() if result.returncode != 0 else None,
        }
    except subprocess.TimeoutExpired:
        return {"success": False, "output": None, "error": f"Timed out after {timeout}s"}
    except Exception as e:
        return {"success": False, "output": None, "error": str(e)}


@app.post("/webhook/claude", response_model=CommandResponse)
async def handle_webhook(
    cmd: CommandRequest,
    request: Request,
    x_webhook_signature: str = Header(None),
):
    """Execute a Claude Code command via webhook."""
    # Verify signature
    if x_webhook_signature:
        body = await request.body()
        if not verify_signature(body, x_webhook_signature):
            raise HTTPException(status_code=401, detail="Invalid signature")

    # Rate limiting
    user_key = cmd.user_id or request.client.host
    if not check_rate_limit(user_key):
        raise HTTPException(status_code=429, detail="Rate limit exceeded")

    logger.info(f"Webhook from {user_key}: {cmd.command[:100]}")

    start_time = time.time()

    loop = asyncio.get_event_loop()
    result = await loop.run_in_executor(
        executor,
        lambda: run_claude(
            cmd.command,
            cmd.working_dir,
            cmd.timeout or COMMAND_TIMEOUT,
        ),
    )

    duration = time.time() - start_time

    return CommandResponse(
        success=result["success"],
        output=result["output"],
        error=result["error"],
        duration_seconds=round(duration, 2),
    )


def check_rate_limit(user_key: str) -> bool:
    now = time.time()
    hour_ago = now - 3600
    rate_limits[user_key] = [t for t in rate_limits[user_key] if t > hour_ago]
    if len(rate_limits[user_key]) >= RATE_LIMIT:
        return False
    rate_limits[user_key].append(now)
    return True


@app.get("/health")
async def health():
    return {"status": "ok", "timestamp": time.time()}

To invoke this webhook from any platform, a POST request is sent as shown below:

curl -X POST http://your-server:8080/webhook/claude \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=..." \
  -d '{"command": "list all Python files", "user_id": "user123"}'

This approach is compatible with Microsoft Teams (outgoing webhooks), WhatsApp (via Twilio webhooks), LINE (via messaging API webhooks), and essentially any platform capable of issuing HTTP POST requests. The platform is configured to send messages to the webhook URL, and the bridge handles the remainder.

Security Best Practices

Granting a chat message the ability to execute code on a machine is powerful and, when handled carelessly, also dangerous. Security is not optional in this context and is the most important component of the entire setup.

The Security Checklist

Implementing a Command Allowlist

Rather than permitting arbitrary prompts, a set of approved command patterns should be defined:

import re

ALLOWED_PATTERNS = [
    r"^list\s",           # List files, functions, etc.
    r"^explain\s",        # Explain code
    r"^run tests",        # Run test suite
    r"^deploy\s",         # Deploy
    r"^fix\s",            # Fix bugs
    r"^review\s",         # Code review
    r"^git\s(status|log|diff|branch)",  # Read-only git
    r"^show\s",           # Show file contents
    r"^analyze\s",        # Analyze code
    r"^write tests",      # Write tests
]

BLOCKED_PATTERNS = [
    r"rm\s+-rf",          # Never allow recursive delete
    r"curl.*\|.*sh",      # No pipe-to-shell
    r"eval\(",            # No eval
    r"exec\(",            # No exec
    r"__import__",        # No dynamic imports
    r"(password|secret|token|key)\s*=",  # No credential setting
]


def is_command_allowed(prompt: str) -> tuple[bool, str]:
    """Check if a command is allowed. Returns (allowed, reason)."""
    prompt_lower = prompt.lower().strip()

    # Check blocklist first
    for pattern in BLOCKED_PATTERNS:
        if re.search(pattern, prompt_lower):
            return False, f"Blocked pattern detected: {pattern}"

    # Check allowlist (if strict mode)
    # For permissive mode, you can skip this check
    for pattern in ALLOWED_PATTERNS:
        if re.search(pattern, prompt_lower):
            return True, "Matched allowed pattern"

    return False, "Command does not match any allowed pattern"

Audit Logging

Every command that passes through the bot should be logged with full context. The practice is important for debugging, accountability, and security incident response:

import json
from datetime import datetime, timezone

def log_command(user_id: str, platform: str, command: str, result: dict):
    """Log a command execution to an audit file."""
    entry = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "user_id": user_id,
        "platform": platform,
        "command": command,
        "success": result["success"],
        "output_length": len(result["output"]) if result["output"] else 0,
        "error": result["error"],
    }
    with open("audit_log.jsonl", "a") as f:
        f.write(json.dumps(entry) + "\n")

Production Deployment

Running the bridge with python telegram_bridge.py in a terminal is appropriate for testing. For production, the bridge must start automatically, restart on failure, and run in the background.

Systemd Service File

The file /etc/systemd/system/claude-telegram-bridge.service should be created with the contents below:

[Unit]
Description=Claude Code Telegram Bridge
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/claude-bridge
ExecStart=/home/youruser/claude-bridge/venv/bin/python telegram_bridge.py
Restart=always
RestartSec=10
StandardOutput=append:/var/log/claude-bridge.log
StandardError=append:/var/log/claude-bridge-error.log
Environment=PATH=/home/youruser/.local/bin:/usr/bin:/bin
Environment=HOME=/home/youruser

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/home/youruser/claude-bridge /home/youruser/projects
PrivateTmp=true

[Install]
WantedBy=multi-user.target

The service is then enabled and started:

sudo systemctl daemon-reload
sudo systemctl enable claude-telegram-bridge
sudo systemctl start claude-telegram-bridge

# Check status
sudo systemctl status claude-telegram-bridge

# View logs
sudo journalctl -u claude-telegram-bridge -f

Docker Deployment

For containerised deployments, the following Dockerfile may be used:

FROM python:3.12-slim

WORKDIR /app

# Install Claude Code CLI (Node.js required)
RUN apt-get update && apt-get install -y curl && \
    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    npm install -g @anthropic-ai/claude-code && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY telegram_bridge.py .
COPY .env .

CMD ["python", "telegram_bridge.py"]

A corresponding docker-compose.yml follows:

version: "3.8"
services:
  claude-bridge:
    build: .
    restart: always
    env_file: .env
    volumes:
      - /home/youruser/projects:/projects:rw
      - claude-config:/root/.claude
    environment:
      - CLAUDE_WORK_DIR=/projects
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  claude-config:

SSH Tunnel Approach

If the bridge server should reside on a VPS for reliability and a public IP while Claude Code remains on the local machine, an SSH tunnel can be used. The bridge connects via SSH to the development machine to invoke Claude Code:

def run_claude_via_ssh(prompt: str, ssh_host: str = "dev-machine") -> dict:
    """Run Claude Code on a remote machine via SSH."""
    # Escape the prompt for shell safety
    import shlex
    safe_prompt = shlex.quote(prompt)

    try:
        result = subprocess.run(
            ["ssh", ssh_host, f"cd ~/projects && claude -p {safe_prompt}"],
            capture_output=True, text=True, timeout=COMMAND_TIMEOUT,
        )
        return {
            "success": result.returncode == 0,
            "output": result.stdout.strip(),
            "error": result.stderr.strip() if result.returncode != 0 else None,
        }
    except Exception as e:
        return {"success": False, "output": None, "error": str(e)}

This pattern combines the advantages of both configurations: the bridge server is always available on the VPS, while Claude Code runs on the more powerful development machine with access to all projects. SSH key authentication should be configured so that no password is needed, and autossh should be used to keep the connection alive.

Practical Workflow Examples

Theoretical discussion alone is insufficient. The following real-world scenarios illustrate where remote control of Claude Code is particularly valuable.

Morning Standup from a Phone

At 8:55 AM, a developer is walking to the office with a coffee. The phone is used to send:

/run Summarize: last 3 git commits, current branch status, any failing tests, and open PRs

By the time the developer sits down at the desk, Claude Code has replied with a clean summary of the project state. The developer enters the standup with a clear understanding of current status.

Deploy from Anywhere

A product manager sends a message: “Can we push the latest to staging for the client demo in an hour?” The developer is at lunch. The response is straightforward:

/deploy staging

The bot responds with the build log, deployment URL, and health check results. The staging URL is forwarded to the product manager, after which the meal resumes.

Quick Bug Fix

An error alert fires at 10 PM while the developer is watching a film. Instead of getting up to use a computer, the following command is issued:

/run The error log shows a TypeError in src/auth.py line 42. Fix it, write a test for the fix, and show me the diff.

Claude Code analyses the error, fixes the bug, writes a regression test, runs the test suite, and returns the diff and test results. The diff is reviewed on the phone screen, and, if satisfactory:

/run Commit the changes with message "fix: handle None auth token in validate_session" and push to a new branch fix/auth-none-check, then create a PR

Code Review on the Go

A team member submits a pull request while the reviewer is commuting:

/run Review PR #123 on GitHub. Summarize changes, identify potential issues, check test coverage, and give your recommendation.

A structured review is returned with file-by-file analysis, flagged concerns, and an overall recommendation, all conducted from the train.

Monitoring and Notifications

The discussion has so far concerned reactive usage, in which a command is sent and a response is received. Proactive monitoring may also be configured, in which the system dispatches alerts and the user responds with actions.

Scheduled Monitoring Script

#!/usr/bin/env python3
"""
Scheduled monitoring that sends alerts via Telegram.
Run via cron: */30 * * * * /path/to/monitor.py
"""

import os
import subprocess
import requests
from dotenv import load_dotenv

load_dotenv()

BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
CHAT_ID = os.getenv("TELEGRAM_ALERT_CHAT_ID")
WORK_DIR = os.getenv("CLAUDE_WORK_DIR")


def send_telegram(message: str):
    url = f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage"
    requests.post(url, json={"chat_id": CHAT_ID, "text": message})


def check_tests():
    """Run tests and alert on failure."""
    result = subprocess.run(
        ["claude", "-p", "Run the test suite. Report ONLY if there are failures. If all pass, say PASS."],
        capture_output=True, text=True, timeout=300, cwd=WORK_DIR,
        env={**os.environ, "TERM": "dumb"},
    )
    output = result.stdout.strip()
    if "PASS" not in output.upper() or result.returncode != 0:
        send_telegram(f"Test failure detected:\n\n{output[:3000]}")


def check_server_health():
    """Check if the production server is healthy."""
    try:
        r = requests.get("https://your-app.com/health", timeout=10)
        if r.status_code != 200:
            send_telegram(f"Server health check failed: HTTP {r.status_code}")
    except Exception as e:
        send_telegram(f"Server unreachable: {e}")


if __name__ == "__main__":
    check_tests()
    check_server_health()

The script should be added to crontab to run every 30 minutes. When a failure occurs, a Telegram notification is dispatched, and a command to remedy the issue can be sent immediately, all from the phone.

CI/CD Integration

A webhook call may be added to the CI/CD pipeline (GitHub Actions, GitLab CI, and similar) so that build failures notify the bot:

# In your GitHub Actions workflow (.github/workflows/ci.yml)
- name: Notify on failure
  if: failure()
  run: |
    curl -s -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage" \
      -d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
      -d text="CI failed on ${{ github.ref }} by ${{ github.actor }}. Reply /run investigate the CI failure and suggest fixes."

The arrangement creates a natural loop: CI fails, a notification arrives, a fix command is sent from the phone, and CI passes—all without opening a laptop.

Limitations and Workarounds

The setup is powerful but has genuine limitations. Awareness of these limitations will spare unnecessary frustration.

Handling Long Output Gracefully

Long output is the most common issue encountered. Claude Code can produce very long output, including test results, code reviews, and diffs. The following pattern is robust across all platforms:

def format_output(output: str, max_length: int, platform: str) -> dict:
    """
    Format output for a messaging platform.
    Returns {text: str, file: str|None} where file is a path to upload if needed.
    """
    if not output:
        return {"text": "(no output)", "file": None}

    if len(output) <= max_length:
        return {"text": output, "file": None}

    # Create a summary + file for long output
    import tempfile
    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False)
    tmp.write(output)
    tmp.close()

    summary = output[:max_length - 200]
    summary += f"\n\n... Output truncated ({len(output)} chars). Full output attached as file."

    return {"text": summary, "file": tmp.name}

Adding Progress Updates

For long-running tasks, prolonged silence is unhelpful. Periodic "still working" updates can be sent as follows:

async def run_with_progress(prompt, send_update, interval=30):
    """Run Claude Code with periodic progress updates."""
    import asyncio
    from concurrent.futures import ThreadPoolExecutor

    executor = ThreadPoolExecutor(max_workers=1)
    loop = asyncio.get_event_loop()
    future = loop.run_in_executor(executor, lambda: run_claude(prompt))

    elapsed = 0
    while not future.done():
        await asyncio.sleep(interval)
        elapsed += interval
        await send_update(f"Still working... ({elapsed}s elapsed)")

    return await future

Final Thoughts

What began as a simple idea—controlling Claude Code from a phone—has the potential to alter development workflows fundamentally. The ability to trigger deployments, repair bugs, run tests, and review code from any location at any time eliminates the final friction between conceiving an action and executing it.

The technical implementation is remarkably straightforward: it is essentially a messaging bot that calls claude -p in a subprocess. The complexity resides in the details, including security, reliability, and output handling, all of which have been examined in detail.

A recommended path forward is as follows:

1. Start with Telegram. Setup takes approximately 15 minutes, costs nothing, and requires no infrastructure. The Telegram bridge script from this guide may be copied and executed directly.
2. Add security. User authentication, rate limiting, and command allowlisting should be configured before access is shared with others.
3. Graduate to Slack when team access is required, or remain with Telegram for personal use.
4. Deploy properly with systemd or Docker once the system is in daily use.
5. Add monitoring to provide proactive alerts and scheduled reports.

The bridge pattern described here is platform-agnostic. Once understood, it can be adapted to WhatsApp, LINE, Microsoft Teams, or any messaging platform that supports bots or webhooks. The core sequence remains the same: receive a message, run claude -p, and return the result.

The future of development is not constrained by physical attachment to a desk. Development tools should be available wherever the developer happens to be. Claude Code already performs the substantive work of understanding and modifying code; the messaging bridge simply makes it accessible from the device that the user carries everywhere—the phone.

References

• Claude Code Documentation — Anthropic
• Telegram Bot API Documentation
• Slack API — Building Apps
• Discord Developer Documentation
• python-telegram-bot Library Documentation
• Slack Bolt for Python
• discord.py Library Documentation
• FastAPI Documentation
• systemd Service Unit Configuration
• ngrok Documentation — Tunneling for Webhooks

This post examines how an automated workflow pipeline connecting Claude Code to Notion can reduce the administrative overhead that consumes a significant portion of a developer’s workweek. A software engineer at a fast-growing startup recently observed that more time was being spent updating Jira tickets than writing code. The observation was not exaggerated. Research from Atlassian suggests that developers spend approximately 30% of their workweek on project-management overhead — updating statuses, writing ticket descriptions, copying PR links into boards, and documenting features after they have been built. That amounts to nearly a day and a half each week consumed by administrative work that adds no lines of working code to the product.

A different configuration is possible. A developer opens the Notion workspace, reviews the sprint board, and issues a single command. An AI agent reads the task description, creates a feature branch, writes the code, runs the tests, opens a pull request, pastes the PR link back into Notion, and updates the status to “In Review” — all before a morning coffee is finished. This is the result when Claude Code, Anthropic’s agentic AI coding tool, is connected to Notion, the workspace in which millions of teams organise their work.

Most developers and knowledge workers operate in two environments: a code editor and a project-management tool. Claude Code is reshaping software development by functioning as an autonomous coding agent that reads requirements, generates code, writes tests, and commits changes. Notion is the location where teams organise everything from product roadmaps to bug trackers to engineering wikis. Independently, each is powerful. When connected through a well-designed automated pipeline, the combination becomes genuinely transformative: a system in which tasks flow from idea to deployed code with minimal human friction, while humans remain in the loop for the decisions that matter.

This guide describes how to build the pipeline from scratch. It covers the architecture, the Notion setup, the MCP (Model Context Protocol) integration, five custom Claude Code commands that handle every stage of the workflow, a complete Python orchestrator script, and advanced patterns for bug fixes, documentation, and sprint planning. By the end, the reader will possess a copy-paste-ready system that turns a Notion board into a command centre for AI-assisted development.

Why Claude Code Combined with Notion?

Before the technical setup is discussed, the fundamental question deserves a direct answer: why this particular combination? Dozens of AI coding tools and project-management platforms exist. What makes Claude Code and Notion uniquely suited to an automated workflow pipeline?

Claude Code: Beyond Code Autocompletion

Claude Code is Anthropic’s command-line AI coding agent. Unlike inline code-completion tools that suggest the next few tokens as the developer types, Claude Code operates at the task level. The developer provides a goal — “add user authentication with JWT tokens” — and Claude Code determines which files to create, which existing files to modify, what tests to write, and how to integrate everything. It reads the entire codebase for context, learns the project’s conventions from a CLAUDE.md file, and can execute shell commands, run tests, and create git commits autonomously.

The capabilities that make it ideal for pipeline automation include agentic execution (multi-step tasks run without supervision), custom slash commands (reusable workflows defined as markdown files), MCP support (connection to external tools and APIs through Anthropic’s Model Context Protocol), and CLI mode (non-interactive invocation from scripts, which is essential for automation).

Notion: A Flexible Programmable Backbone

Notion provides a fully programmable workspace. Its database system allows the creation of structured project boards with custom properties — status columns, priority levels, assignees, URLs, dates, and rich-text fields. Crucially, Notion has a robust API that allows external systems to read and write data, and it supports webhooks for real-time notifications. The pipeline can therefore query Notion for pending tasks, update statuses as work progresses, and write back results such as PR URLs and code summaries.

In Combination: An Automated Development Workflow

Connecting Claude Code to Notion creates a closed-loop system. A task is created in Notion. Claude Code retrieves it, reads the requirements, writes the code, opens a PR, and updates Notion — all through a sequence of automated stages. The human developer’s role shifts from manually performing every step to reviewing PRs, approving deployments, and steering the project at a higher level.

How does this approach compare with other popular combinations? The landscape is summarised below:

The Claude Code and Notion stack wins on automation because Claude Code can execute entire tasks autonomously (not merely suggest code snippets), and Notion’s API and database model make it straightforward to build structured workflows that other tools can interact with programmatically. The setup procedure follows.

Architecture Overview

Before any configuration is written, the full pipeline architecture warrants examination. The end-to-end system flow is as follows:

The Pipeline Flow

The workflow follows a linear progression with feedback loops at each stage:

┌─────────────────────────────────────────────────────────────────┐
│                    NOTION WORKSPACE                              │
│                                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐     │
│  │  To Do   │──▶│In Progress│──▶│In Review │──▶│   Done   │     │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘     │
│       │              ▲              ▲              ▲             │
└───────┼──────────────┼──────────────┼──────────────┼─────────────┘
        │              │              │              │
        ▼              │              │              │
┌───────────────┐      │              │              │
│  /pick-task   │──────┘              │              │
│  (select +    │                     │              │
│   branch)     │                     │              │
└───────┬───────┘                     │              │
        ▼                             │              │
┌───────────────┐                     │              │
│  /work-task   │                     │              │
│  (code +      │                     │              │
│   test)       │                     │              │
└───────┬───────┘                     │              │
        ▼                             │              │
┌───────────────┐                     │              │
│ /submit-task  │─────────────────────┘              │
│  (PR + link)  │                                    │
└───────┬───────┘                                    │
        ▼                                            │
┌───────────────┐                                    │
│/complete-task │────────────────────────────────────┘
│  (merge +     │
│   archive)    │
└───────────────┘

Core Components

The pipeline relies on five key components working together:

Notion API — The data layer. It stores tasks, statuses, priorities, PR links, and documentation. Notion’s database functions as the single source of truth for what must be built and what has been completed.

Claude Code CLI — The execution engine. It receives task requirements, generates code, writes tests, creates commits, and interacts with git. It may be invoked interactively (when a developer runs slash commands) or non-interactively (when an orchestrator script spawns Claude Code processes).

MCP (Model Context Protocol) Servers — The bridge. MCP is Anthropic’s open standard for connecting AI models to external tools and data sources. A Notion MCP server gives Claude Code direct access to read and write Notion databases without requiring custom API code.

Git plus GitHub CLI (gh) — The version-control layer. Claude Code creates branches, commits changes, and opens pull requests using standard git commands and the GitHub CLI.

Orchestrator Script — The automation glue. A Python script polls Notion for new tasks, spawns Claude Code processes, handles errors, and manages the overall workflow lifecycle.

When to Use Webhooks, Polling, or Manual Triggers

Three options exist for triggering the pipeline, and the appropriate choice depends on the team’s needs:

Manual triggers are the simplest starting point. A developer opens a terminal, runs /pick-task, and the pipeline executes step by step under supervision. This provides maximum control and is ideal during initial adoption of the workflow.

Polling involves running a script on a schedule (e.g., every five minutes via cron) that checks Notion for tasks in the “To Do” column and processes them automatically. This is a sound middle ground: it is easy to implement, easy to debug, and reliable enough for most teams.

Webhooks provide real-time triggers. Notion can send a webhook when a database entry changes, allowing the pipeline to react instantly when a new task is created. This requires a web server to receive the webhooks, which adds complexity, but provides the fastest response time.

Setting Up the Foundation

The following section covers the complete setup for both Notion and Claude Code, from creating the first integration to configuring MCP.

Notion Setup

The initial requirements are a Notion integration and a structured project database. The step-by-step process follows.

Step 1: Create a Notion Internal Integration. Navigate to notion.so/my-integrations and click “New integration.” Provide a name such as “Claude Code Pipeline,” select the workspace in which the project resides, and set the capabilities to “Read content,” “Update content,” and “Insert content.” Once created, copy the Internal Integration Secret — this is the API key. It begins with ntn_ and will be required for the MCP configuration.

Step 2: Create the Project Database. In the Notion workspace, create a new full-page database (not an inline one). This database will serve as the task board. The following properties should be set up:

Step 3: Share the Database with the Integration. Open the database page, click the three-dot menu in the upper right, select “Connections,” and add the “Claude Code Pipeline” integration created earlier. This grants the integration permission to read and modify the database. Without this step, all API calls return 404 errors — a common source of confusion.

Step 4: Copy the Database ID. Open the database in a browser. The URL has the form https://www.notion.so/yourworkspace/abc123def456.... The 32-character hexadecimal string following the workspace name (and preceding any ?v= query parameter) is the database ID. It is required for querying tasks.

Claude Code Setup

The next step is to install and configure Claude Code for the pipeline workflow.

Install Claude Code globally via npm:

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

Configure the project’s CLAUDE.md file. This file resides at the root of the repository and provides Claude Code with persistent context about the project. A well-written CLAUDE.md dramatically improves code quality because Claude Code reads it before every task:

# CLAUDE.md — Project Context for Claude Code

## Project Overview
This is a [your framework] application that [brief description].

## Tech Stack
- Language: Python 3.12 / TypeScript 5.x
- Framework: FastAPI / Next.js
- Database: PostgreSQL with SQLAlchemy
- Testing: pytest / vitest

## Code Conventions
- Use type hints on all function signatures
- Follow PEP 8 / ESLint defaults
- Write docstrings for public functions
- Tests live in tests/ mirroring the src/ structure

## Key Commands
- Run tests: `pytest -v`
- Start dev server: `uv run python -m src.main`
- Lint: `ruff check .`

## Notion Integration
- Database ID: <your-database-id>
- Task statuses: To Do → In Progress → In Review → Done
- All task updates should go through the Notion MCP server

Create the custom-commands directory. Claude Code looks for command definitions in .claude/commands/. Each .md file becomes a slash command that can be invoked inside Claude Code:

mkdir -p .claude/commands

These command files will be populated in the pipeline section below. Before that, Claude Code must be connected to Notion.

Connecting Claude Code to Notion via MCP

This is the principal integration step. MCP (Model Context Protocol) is Anthropic’s open standard for connecting AI models to external tools and data sources. It functions as a universal adapter; rather than writing custom API integration code for every service, the developer configures an MCP server that exposes the service’s capabilities in a format Claude Code understands natively.

What MCP Does

An MCP server is a lightweight process that runs alongside Claude Code and translates between the AI model and an external API. When Claude Code needs to read a Notion database, it sends a structured request to the MCP server, which translates it into a Notion API call, receives the response, and returns the data in a format Claude can use. None of this plumbing is written by the developer; the MCP server handles it.

For the Notion integration, the official @notionhq/notion-mcp-server package is used. It exposes Notion operations as MCP tools that Claude Code can invoke.

Setting Up the Notion MCP Server

Create or edit .claude/settings.json in the project root with the following configuration:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_YOUR_API_KEY_HERE\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

An alternative is the community-driven notion-mcp server, which some developers prefer for its broader feature set:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "ntn_YOUR_API_KEY_HERE"
      }
    }
  }
}

Testing the Connection

Launch Claude Code in the project directory and test the Notion connection:

claude

# Once inside Claude Code, try:
> List all tasks in my Notion project database

# Claude Code should use the MCP server to query your database
# and return the list of tasks with their statuses

If the connection works, Claude Code will be observed invoking the Notion MCP tools to query the database and return results. If the connection fails, verify that the API key is correct, that the database has been shared with the integration, and that the MCP server package is installable via npx.

Available Notion Operations via MCP

Once configured, Claude Code can perform the following operations through the MCP server:

• Query databases — Filter and sort tasks by status, priority, type, or any other property
• Read pages — Retrieve the full content of a task, including its description and acceptance criteria
• Update properties — Change a task’s status, add PR URLs, set dates, update text fields
• Create pages — Add new tasks, create documentation pages, generate sub-tasks
• Search — Find pages across the workspace by keyword
• Append blocks — Add content (text, code blocks, headings) to existing pages

These operations form the building blocks for every stage of the pipeline. They are now ready to be used.

Building the Workflow Pipeline Step by Step

This section is the core of the guide. Five custom Claude Code commands are constructed, each handling one stage of the development lifecycle. Every command file below is complete and copy-paste ready; saving each one to .claude/commands/ permits immediate use.

Pipeline Stage 1: Task Intake — /pick-task

The first stage selects a task from Notion and prepares the local development environment. Create the file .claude/commands/pick-task.md:

# Pick Task from Notion

You are a development workflow assistant. Your job is to select a task
from the Notion project database and prepare the local environment.

## Steps

1. **Query Notion for available tasks:**
   - Use the Notion MCP server to query the project database
   - Filter for tasks where Status = "To Do"
   - Sort by Priority (Critical first, then High, Medium, Low)
   - Display the results as a numbered list showing:
     Title | Priority | Type

2. **Let the user select a task:**
   - If $ARGUMENTS contains a task number or title, use that
   - Otherwise, ask the user to pick from the list

3. **Update Notion status:**
   - Set the selected task's Status to "In Progress"
   - Add a note to the Claude Code Log: "Task picked up at [timestamp]"

4. **Create a git branch:**
   - Generate a branch name from the task title:
     - Lowercase, hyphens instead of spaces
     - Prefix with task type: feature/, bugfix/, refactor/, docs/
     - Example: "Add user authentication" → feature/add-user-authentication
   - Run: git checkout -b <branch-name>
   - Update the Branch Name property in Notion with the branch name

5. **Display the task details:**
   - Show the full task description and any acceptance criteria
   - Confirm the branch was created
   - Suggest running /work-task to start coding

When /pick-task is run inside Claude Code, the system queries the Notion database, presents the available tasks, creates the appropriate git branch, and updates Notion — all in a single interaction.

Pipeline Stage 2: Code Generation — /work-task

This stage exercises Claude Code’s primary capability: writing code. Create .claude/commands/work-task.md:

# Work on Current Task

You are a senior software engineer. Your job is to implement the current
task based on the requirements stored in Notion.

## Steps

1. **Identify the current task:**
   - Check the current git branch name
   - Query Notion for the task with a matching Branch Name property
   - Read the full task page content including:
     - Description
     - Acceptance criteria
     - Any linked documents or specifications
     - Comments from team members

2. **Plan the implementation:**
   - Analyze the requirements
   - List the files that need to be created or modified
   - Identify potential edge cases
   - Present the plan to the user for approval

3. **Implement the code:**
   - Write clean, well-documented code following project conventions
   - Follow patterns established in CLAUDE.md
   - Create or modify files as needed
   - Add appropriate error handling
   - Include type hints / types where applicable

4. **Write tests:**
   - Write unit tests covering the main functionality
   - Write edge case tests
   - Ensure tests follow the project's testing patterns

5. **Run tests and iterate:**
   - Execute the test suite
   - If tests fail, fix the code and re-run
   - Continue until all tests pass

6. **Update Notion with progress:**
   - Add implementation notes to the Claude Code Log
   - Note: "Implementation complete. Tests passing. [timestamp]"

7. **Suggest next steps:**
   - Recommend running /submit-task to create a PR

Pipeline Stage 3: Code Review and PR — /submit-task

Once the code has been written and tested, this command handles the submission process. Create .claude/commands/submit-task.md:

# Submit Task — Create PR and Update Notion

You are a development workflow assistant. Your job is to commit the
current changes, create a pull request, and update the Notion task.

## Steps

1. **Review changes:**
   - Run `git status` and `git diff` to see all changes
   - Summarize what was implemented

2. **Create a meaningful commit:**
   - Stage all relevant files (avoid committing .env or secrets)
   - Write a descriptive commit message following conventional commits:
     feat: Add user authentication with JWT tokens

     - Implement login and register endpoints
     - Add JWT token generation and validation middleware
     - Create user model with password hashing
     - Add comprehensive test suite

3. **Push and create PR:**
   - Push the branch to origin: `git push -u origin HEAD`
   - Create a pull request using the GitHub CLI:
     ```
     gh pr create \
       --title "feat: [task title from Notion]" \
       --body "[generated description with summary, changes list,
               test coverage, and link to Notion task]"
     ```

4. **Update Notion:**
   - Set Status to "In Review"
   - Set PR URL to the pull request URL
   - Add to Claude Code Log: "PR created: [URL] at [timestamp]"
   - Add a summary of all changes made to the task page body

5. **Notify:**
   - Display the PR URL
   - Show a summary of the submission
   - Suggest the reviewer check the PR

Pipeline Stage 4: Documentation — /doc-task

Documentation is often the first item sacrificed under tight deadlines. This command automates it. Create .claude/commands/doc-task.md:

# Document Current Task

You are a technical writer. Your job is to generate documentation
for the changes made in the current task.

## Steps

1. **Identify the current task:**
   - Check the current git branch name
   - Query Notion for the matching task

2. **Analyze the changes:**
   - Run `git diff main...HEAD` to see all changes in this branch
   - Understand the purpose, architecture, and usage of the new code

3. **Generate documentation:**
   - Create a new page in Notion under the project's Docs section
   - Include:
     - Overview: What was built and why
     - Architecture: How the components fit together
     - API Reference: Endpoints, functions, or classes with parameters
     - Usage Examples: Code snippets showing how to use the feature
     - Configuration: Any environment variables or settings needed
     - Troubleshooting: Common issues and solutions

4. **Link documentation:**
   - Add the Docs Page relation in the original Notion task
   - Update Claude Code Log: "Documentation created at [timestamp]"

5. **Update README if needed:**
   - If the changes introduce new setup steps or commands,
     update the project README.md accordingly

Pipeline Stage 5: Completion — /complete-task

The final stage closes the loop. Create .claude/commands/complete-task.md:

# Complete Task — Close the Loop

You are a development workflow assistant. Your job is to finalize
a completed task after its PR has been merged.

## Steps

1. **Verify the PR is merged:**
   - Check the current branch or accept a task identifier from $ARGUMENTS
   - Query Notion for the task
   - Use `gh pr status` or `gh pr view` to confirm the PR was merged

2. **Update Notion:**
   - Set Status to "Done"
   - Set Completed At to the current date/time
   - Add to Claude Code Log: "Task completed at [timestamp]"

3. **Clean up the branch:**
   - Switch to main: `git checkout main`
   - Pull latest: `git pull origin main`
   - Delete the local branch: `git branch -d <branch-name>`
   - Delete the remote branch: `git push origin --delete <branch-name>`

4. **Generate a changelog entry:**
   - Create or append to a Changelog page in Notion
   - Entry format:
     **[Date] - [Task Title]**
     - Summary of changes
     - PR: [link]
     - Type: [Feature/Bug Fix/Refactor/Docs]

5. **Display completion summary:**
   - Show task title, completion time, PR link
   - Calculate time from "In Progress" to "Done" if dates are available

With these five commands, the complete task lifecycle is managed through Claude Code and Notion. The pipeline can be extended further by automating the orchestration itself.

Automation Script: The Orchestrator

The custom commands above perform well when a developer is at the keyboard. When the pipeline must run autonomously — picking up tasks and processing them without human intervention — an orchestrator script is required.

This Python script polls the Notion database for new tasks, spawns Claude Code in non-interactive mode to process each one, handles errors with retry logic, and logs all events back to Notion.

#!/usr/bin/env python3
"""
workflow_orchestrator.py — Automated Claude Code + Notion Pipeline

Polls Notion for "To Do" tasks and processes them using Claude Code
in non-interactive mode. Handles errors, retries, and notifications.

Usage:
    python workflow_orchestrator.py --once          # Process one batch
    python workflow_orchestrator.py --watch          # Continuous polling
    python workflow_orchestrator.py --interval 300   # Poll every 5 minutes
"""

import argparse
import json
import logging
import os
import subprocess
import sys
import time
from datetime import datetime, timezone
from dataclasses import dataclass, field
from pathlib import Path

import httpx  # pip install httpx

# ─── Configuration ───────────────────────────────────────────────

NOTION_API_KEY = os.environ["NOTION_API_KEY"]
NOTION_DATABASE_ID = os.environ["NOTION_DATABASE_ID"]
PROJECT_DIR = os.environ.get("PROJECT_DIR", os.getcwd())
MAX_RETRIES = 3
POLL_INTERVAL = 300  # seconds (5 minutes default)
NOTION_API_URL = "https://api.notion.com/v1"
NOTION_VERSION = "2022-06-28"

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler("orchestrator.log"),
    ],
)
logger = logging.getLogger(__name__)


# ─── Data Models ─────────────────────────────────────────────────

@dataclass
class NotionTask:
    page_id: str
    title: str
    status: str
    priority: str
    task_type: str
    description: str = ""
    branch_name: str = ""
    pr_url: str = ""

    @property
    def safe_branch_name(self) -> str:
        prefix_map = {
            "Feature": "feature",
            "Bug": "bugfix",
            "Refactor": "refactor",
            "Docs": "docs",
        }
        prefix = prefix_map.get(self.task_type, "task")
        slug = self.title.lower()
        slug = "".join(c if c.isalnum() or c == " " else "" for c in slug)
        slug = slug.strip().replace(" ", "-")[:50]
        return f"{prefix}/{slug}"


# ─── Notion API Client ──────────────────────────────────────────

class NotionClient:
    def __init__(self, api_key: str):
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Notion-Version": NOTION_VERSION,
        }
        self.client = httpx.Client(
            base_url=NOTION_API_URL,
            headers=self.headers,
            timeout=30.0,
        )

    def query_tasks(self, status: str = "To Do") -> list[NotionTask]:
        """Query the database for tasks with a given status."""
        payload = {
            "filter": {
                "property": "Status",
                "select": {"equals": status},
            },
            "sorts": [
                {
                    "property": "Priority",
                    "direction": "ascending",
                }
            ],
        }
        resp = self.client.post(
            f"/databases/{NOTION_DATABASE_ID}/query",
            json=payload,
        )
        resp.raise_for_status()
        results = resp.json().get("results", [])

        tasks = []
        for page in results:
            props = page["properties"]
            title_parts = props.get("Title", {}).get("title", [])
            title = title_parts[0]["plain_text"] if title_parts else "Untitled"

            tasks.append(NotionTask(
                page_id=page["id"],
                title=title,
                status=status,
                priority=self._get_select(props, "Priority"),
                task_type=self._get_select(props, "Type"),
            ))
        return tasks

    def update_status(self, page_id: str, status: str):
        """Update a task's status property."""
        self.client.patch(
            f"/pages/{page_id}",
            json={
                "properties": {
                    "Status": {"select": {"name": status}},
                }
            },
        ).raise_for_status()
        logger.info(f"Updated {page_id} status to '{status}'")

    def update_property(self, page_id: str, property_name: str,
                        value: str, prop_type: str = "rich_text"):
        """Update a text or URL property on a task."""
        if prop_type == "url":
            prop_value = {"url": value}
        elif prop_type == "date":
            prop_value = {"date": {"start": value}}
        else:
            prop_value = {
                "rich_text": [{"text": {"content": value}}]
            }
        self.client.patch(
            f"/pages/{page_id}",
            json={"properties": {property_name: prop_value}},
        ).raise_for_status()

    def append_log(self, page_id: str, message: str):
        """Append a timestamped log entry to the page body."""
        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
        self.client.patch(
            f"/blocks/{page_id}/children",
            json={
                "children": [
                    {
                        "object": "block",
                        "type": "paragraph",
                        "paragraph": {
                            "rich_text": [
                                {
                                    "type": "text",
                                    "text": {
                                        "content": f"[{timestamp}] {message}"
                                    },
                                }
                            ]
                        },
                    }
                ]
            },
        ).raise_for_status()

    @staticmethod
    def _get_select(props: dict, name: str) -> str:
        sel = props.get(name, {}).get("select")
        return sel["name"] if sel else ""


# ─── Claude Code Runner ─────────────────────────────────────────

class ClaudeCodeRunner:
    def __init__(self, project_dir: str):
        self.project_dir = project_dir

    def run_command(self, prompt: str, timeout: int = 600) -> tuple[bool, str]:
        """
        Run Claude Code in non-interactive mode with a prompt.
        Returns (success: bool, output: str).
        """
        cmd = [
            "claude",
            "--print",       # non-interactive, print output
            "--dangerously-skip-permissions",
            prompt,
        ]
        logger.info(f"Running Claude Code: {prompt[:80]}...")
        try:
            result = subprocess.run(
                cmd,
                cwd=self.project_dir,
                capture_output=True,
                text=True,
                timeout=timeout,
            )
            output = result.stdout + result.stderr
            success = result.returncode == 0
            if not success:
                logger.error(f"Claude Code failed: {output[-500:]}")
            return success, output
        except subprocess.TimeoutExpired:
            logger.error(f"Claude Code timed out after {timeout}s")
            return False, "Process timed out"
        except Exception as e:
            logger.error(f"Claude Code error: {e}")
            return False, str(e)


# ─── Pipeline Orchestrator ───────────────────────────────────────

class PipelineOrchestrator:
    def __init__(self):
        self.notion = NotionClient(NOTION_API_KEY)
        self.claude = ClaudeCodeRunner(PROJECT_DIR)

    def process_task(self, task: NotionTask) -> bool:
        """Process a single task through the full pipeline."""
        logger.info(f"Processing task: {task.title} ({task.task_type})")

        # Stage 1: Set up branch
        self.notion.update_status(task.page_id, "In Progress")
        self.notion.append_log(task.page_id, "Pipeline started")

        branch = task.safe_branch_name
        subprocess.run(
            ["git", "checkout", "-b", branch],
            cwd=PROJECT_DIR, check=True,
        )
        self.notion.update_property(
            task.page_id, "Branch Name", branch
        )

        # Stage 2: Generate code
        work_prompt = (
            f"Read the following task and implement it:\n"
            f"Title: {task.title}\n"
            f"Type: {task.task_type}\n"
            f"Priority: {task.priority}\n"
            f"Write the code, write tests, and make sure tests pass."
        )
        success, output = self.claude.run_command(work_prompt, timeout=900)
        if not success:
            self._handle_failure(task, "Code generation failed", output)
            return False

        self.notion.append_log(task.page_id, "Code generation complete")

        # Stage 3: Commit, push, create PR
        subprocess.run(
            ["git", "add", "-A"], cwd=PROJECT_DIR, check=True,
        )
        subprocess.run(
            ["git", "commit", "-m", f"feat: {task.title}"],
            cwd=PROJECT_DIR, check=True,
        )
        subprocess.run(
            ["git", "push", "-u", "origin", branch],
            cwd=PROJECT_DIR, check=True,
        )

        pr_result = subprocess.run(
            ["gh", "pr", "create",
             "--title", f"feat: {task.title}",
             "--body", f"Automated PR for: {task.title}"],
            cwd=PROJECT_DIR, capture_output=True, text=True,
        )
        if pr_result.returncode == 0:
            pr_url = pr_result.stdout.strip()
            self.notion.update_property(
                task.page_id, "PR URL", pr_url, prop_type="url"
            )
            self.notion.update_status(task.page_id, "In Review")
            self.notion.append_log(
                task.page_id, f"PR created: {pr_url}"
            )
            logger.info(f"PR created: {pr_url}")
        else:
            self._handle_failure(
                task, "PR creation failed", pr_result.stderr
            )
            return False

        # Return to main branch
        subprocess.run(
            ["git", "checkout", "main"], cwd=PROJECT_DIR, check=True,
        )
        return True

    def _handle_failure(self, task: NotionTask, stage: str, error: str):
        """Handle a pipeline failure by logging to Notion."""
        logger.error(f"Task '{task.title}' failed at: {stage}")
        self.notion.append_log(
            task.page_id, f"FAILED at {stage}: {error[:300]}"
        )
        # Return to main branch on failure
        subprocess.run(
            ["git", "checkout", "main"],
            cwd=PROJECT_DIR, capture_output=True,
        )

    def run_once(self):
        """Process all available 'To Do' tasks once."""
        tasks = self.notion.query_tasks("To Do")
        logger.info(f"Found {len(tasks)} tasks to process")

        for task in tasks:
            for attempt in range(1, MAX_RETRIES + 1):
                logger.info(
                    f"Attempt {attempt}/{MAX_RETRIES} for: {task.title}"
                )
                if self.process_task(task):
                    break
                if attempt < MAX_RETRIES:
                    logger.info("Retrying in 30 seconds...")
                    time.sleep(30)
            else:
                logger.error(
                    f"Task '{task.title}' failed after {MAX_RETRIES} attempts"
                )
                self.notion.update_status(task.page_id, "To Do")
                self.notion.append_log(
                    task.page_id,
                    f"Pipeline failed after {MAX_RETRIES} attempts. "
                    "Returning to To Do for manual review.",
                )

    def watch(self, interval: int = POLL_INTERVAL):
        """Continuously poll for new tasks."""
        logger.info(
            f"Watching for tasks every {interval} seconds. Ctrl+C to stop."
        )
        while True:
            try:
                self.run_once()
            except Exception as e:
                logger.error(f"Watch cycle error: {e}")
            time.sleep(interval)


# ─── Entry Point ─────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(
        description="Claude Code + Notion Workflow Orchestrator"
    )
    parser.add_argument(
        "--once", action="store_true",
        help="Process available tasks once and exit",
    )
    parser.add_argument(
        "--watch", action="store_true",
        help="Continuously poll for new tasks",
    )
    parser.add_argument(
        "--interval", type=int, default=POLL_INTERVAL,
        help=f"Polling interval in seconds (default: {POLL_INTERVAL})",
    )
    args = parser.parse_args()

    orchestrator = PipelineOrchestrator()

    if args.watch:
        orchestrator.watch(args.interval)
    else:
        orchestrator.run_once()


if __name__ == "__main__":
    main()

The orchestrator is invoked as follows:

# Process all current "To Do" tasks once
python workflow_orchestrator.py --once

# Watch continuously, polling every 5 minutes
python workflow_orchestrator.py --watch

# Watch with a custom interval (10 minutes)
python workflow_orchestrator.py --watch --interval 600

For scheduled execution without watch mode, a cron job may be used:

# Edit your crontab
crontab -e

# Add this line to run every 10 minutes
*/10 * * * * cd /path/to/your/project && /usr/bin/python3 workflow_orchestrator.py --once >> /var/log/orchestrator-cron.log 2>&1

Advanced Workflows

The five-stage pipeline covers standard feature development, but real teams require more. The following are specialised workflows for common scenarios.

Bug-Fix Pipeline

Bug fixes follow a pattern different from feature work — they begin with reproduction, then diagnosis, then the fix, then regression testing. Create .claude/commands/fix-bug.md:

# Fix Bug from Notion

You are a senior debugger. A bug has been reported in Notion.
Your job is to reproduce it, find the root cause, fix it,
and write a regression test.

## Steps

1. **Read the bug report:**
   - Query Notion for the task (from $ARGUMENTS or current branch)
   - Extract: steps to reproduce, expected behavior, actual behavior,
     environment details, stack traces, and screenshots described

2. **Reproduce the issue:**
   - Write a failing test that demonstrates the bug
   - Run the test to confirm it fails with the expected error
   - If reproduction fails, add notes to Notion and ask for clarification

3. **Diagnose the root cause:**
   - Trace the code path from the reproduction test
   - Identify the exact line(s) causing the issue
   - Document the root cause in Notion

4. **Implement the fix:**
   - Make the minimal change needed to fix the bug
   - Avoid refactoring unrelated code in a bug fix branch
   - Ensure the failing test now passes

5. **Write regression tests:**
   - Add edge case tests around the fixed code
   - Ensure the full test suite passes

6. **Update Notion:**
   - Add root cause analysis to the task
   - Add the fix description
   - Log: "Bug fixed and regression test added at [timestamp]"

7. **Suggest running /submit-task to create the PR**

Documentation Pipeline

For teams that wish to generate comprehensive documentation from code, create .claude/commands/generate-docs.md:

# Generate Documentation

You are a technical documentation specialist. Generate comprehensive
documentation for the specified module or feature.

## Steps

1. **Identify the target:**
   - If $ARGUMENTS specifies a module, document that module
   - Otherwise, query Notion for tasks tagged "needs docs"

2. **Analyze the codebase:**
   - Read all relevant source files
   - Understand the architecture, data flow, and public API
   - Identify configuration options and environment variables

3. **Generate documentation as a Notion page:**
   - Create a new page in the Docs section of Notion
   - Structure:
     - Overview and purpose
     - Architecture diagram (described in text)
     - API reference with parameters, return types, and examples
     - Configuration guide
     - Troubleshooting FAQ
   - Use Notion's block types: headings, code blocks,
     callouts, tables

4. **Link the documentation:**
   - If created for a specific task, add the Docs Page relation
   - Add to the project's documentation index in Notion

Sprint-Planning Pipeline

Claude Code can decompose high-level user stories into actionable tasks. This workflow reads a user story from Notion, analyses the technical requirements, and creates sub-tasks:

# Sprint Planning Assistant

You are a technical lead helping with sprint planning.

## Steps

1. **Read the user story from Notion:**
   - Query for items tagged as "Epic" or "User Story"
   - Read the full description and acceptance criteria

2. **Analyze technical requirements:**
   - Break down the story into implementation tasks
   - Estimate relative complexity (S/M/L/XL) for each
   - Identify dependencies between tasks
   - Flag any tasks that need clarification

3. **Create sub-tasks in Notion:**
   - For each identified task, create a new page in the database
   - Set properties: Title, Type, Priority, Status = "To Do"
   - Add a relation to the parent story
   - Include acceptance criteria for each sub-task

4. **Present the breakdown:**
   - Display the task tree with estimates
   - Highlight any risks or unknowns
   - Suggest a sprint ordering based on dependencies

Code-Review Pipeline

When a PR is created, Claude Code can perform an initial code review and post findings back to Notion:

# Automated Code Review

You are a senior code reviewer.

## Steps

1. **Get the PR to review:**
   - If $ARGUMENTS contains a PR number, use that
   - Otherwise, query Notion for tasks in "In Review" status

2. **Review the code:**
   - Run `gh pr diff <number>` to see the changes
   - Check for:
     - Code quality and readability
     - Potential bugs or edge cases
     - Test coverage
     - Security issues
     - Performance concerns
     - Adherence to project conventions

3. **Post review comments:**
   - Use `gh pr review <number>` to submit review comments
   - Be constructive and specific
   - Suggest improvements with code examples

4. **Update Notion:**
   - Add review summary to the task's Claude Code Log
   - If changes requested, add specific items to address

Real-World Example: Building a Feature End-to-End

A complete example illustrates how the pieces fit together. Consider a product manager who creates a new task in the Notion database: "Add user authentication with JWT tokens." The task has the following properties:

• Status: To Do
• Priority: High
• Type: Feature
• Description: "Implement user registration and login endpoints with JWT-based authentication. Include password hashing with bcrypt, token refresh mechanism, and role-based access control (admin, user). Protect all existing API endpoints with auth middleware."

The following sequence occurs when the developer engages the pipeline:

Step 1 — Developer runs /pick-task

Claude Code queries the Notion database and presents the available tasks. The developer selects the authentication task. Claude Code updates the Notion status to "In Progress," creates a new git branch called feature/add-user-authentication-with-jwt-tokens, and writes the branch name back to Notion. The developer sees a confirmation with the full task description.

Step 2 — Developer runs /work-task

Claude Code reads the task requirements from Notion, including the description and acceptance criteria. It analyses the existing codebase to understand the project's patterns — the framework in use, the database ORM, and existing route structures. It then presents an implementation plan:

• Create src/models/user.py,User model with password hashing
• Create src/auth/jwt.py—Token generation and validation
• Create src/auth/middleware.py—Authentication middleware
• Create src/routes/auth.py,Login and register endpoints
• Modify src/routes/__init__.py—Register auth routes
• Create tests/test_auth.py—Comprehensive test suite

After the developer approves the plan, Claude Code writes all the files, runs the tests, identifies two failing tests (a missing import and an incorrect assertion), fixes them, and re-runs until everything passes. It updates Notion with a progress note: "Implementation complete. 12 tests passing."

Step 3 — Developer runs /submit-task

Claude Code stages the changes, creates a descriptive commit message, pushes the branch, and opens a PR on GitHub. The PR description includes a summary of changes, the list of new files, test-coverage information, and a link back to the Notion task. Claude Code writes the PR URL to the Notion task and changes the status to "In Review."

Step 4 — Developer optionally runs /doc-task

Claude Code generates a documentation page in Notion covering the authentication system: how JWT tokens work in this project, the API endpoints (POST /auth/register, POST /auth/login, POST /auth/refresh), required environment variables (JWT_SECRET, TOKEN_EXPIRY), and troubleshooting tips for common authentication errors.

Step 5 — After PR review and merge, the developer runs /complete-task

Claude Code verifies that the PR has been merged, updates the Notion status to "Done," sets the completion timestamp, deletes the feature branch (both local and remote), and generates a changelog entry in Notion. The task has progressed from "To Do" to "Done" with minimal manual overhead.

Notion Database Templates

Setting up the appropriate Notion databases from the outset prevents difficulties later. The essential templates and their API payloads for programmatic creation follow.

Sprint-Board Template

The core task board, with columns optimised for the Claude Code pipeline:

To create this database programmatically via the Notion API:

# API payload to create the sprint board database
{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Sprint Board" } }],
  "properties": {
    "Title": { "title": {} },
    "Status": {
      "select": {
        "options": [
          { "name": "Backlog", "color": "default" },
          { "name": "To Do", "color": "blue" },
          { "name": "In Progress", "color": "yellow" },
          { "name": "In Review", "color": "orange" },
          { "name": "Done", "color": "green" }
        ]
      }
    },
    "Priority": {
      "select": {
        "options": [
          { "name": "Critical", "color": "red" },
          { "name": "High", "color": "orange" },
          { "name": "Medium", "color": "yellow" },
          { "name": "Low", "color": "gray" }
        ]
      }
    },
    "Type": {
      "select": {
        "options": [
          { "name": "Feature", "color": "green" },
          { "name": "Bug", "color": "red" },
          { "name": "Refactor", "color": "purple" },
          { "name": "Docs", "color": "blue" }
        ]
      }
    },
    "Branch Name": { "rich_text": {} },
    "PR URL": { "url": {} },
    "Completed At": { "date": {} },
    "Claude Code Log": { "rich_text": {} }
  }
}

Bug-Tracker Template

A specialised database for bug reports with fields that feed directly into the /fix-bug command:

{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Bug Tracker" } }],
  "properties": {
    "Bug Title": { "title": {} },
    "Severity": {
      "select": {
        "options": [
          { "name": "P0 - Critical", "color": "red" },
          { "name": "P1 - High", "color": "orange" },
          { "name": "P2 - Medium", "color": "yellow" },
          { "name": "P3 - Low", "color": "gray" }
        ]
      }
    },
    "Status": {
      "select": {
        "options": [
          { "name": "Reported", "color": "red" },
          { "name": "Investigating", "color": "yellow" },
          { "name": "Fix In Progress", "color": "orange" },
          { "name": "Fixed", "color": "green" },
          { "name": "Won't Fix", "color": "gray" }
        ]
      }
    },
    "Steps to Reproduce": { "rich_text": {} },
    "Expected Behavior": { "rich_text": {} },
    "Actual Behavior": { "rich_text": {} },
    "Root Cause": { "rich_text": {} },
    "Fix PR": { "url": {} },
    "Reported By": { "people": {} },
    "Environment": { "rich_text": {} }
  }
}

Documentation-Wiki Template

A database for auto-generated documentation, linked to sprint-board tasks:

{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Documentation Wiki" } }],
  "properties": {
    "Doc Title": { "title": {} },
    "Category": {
      "select": {
        "options": [
          { "name": "API Reference", "color": "blue" },
          { "name": "Architecture", "color": "purple" },
          { "name": "Setup Guide", "color": "green" },
          { "name": "Runbook", "color": "orange" },
          { "name": "Changelog", "color": "gray" }
        ]
      }
    },
    "Related Task": {
      "relation": {
        "database_id": "YOUR_SPRINT_BOARD_DATABASE_ID"
      }
    },
    "Last Updated": { "date": {} },
    "Generated By": {
      "select": {
        "options": [
          { "name": "Claude Code", "color": "blue" },
          { "name": "Manual", "color": "gray" }
        ]
      }
    }
  }
}

Error Handling and Monitoring

Any automated system requires robust error handling. The following measures make the pipeline resilient.

When Claude Code Fails

Claude Code can fail for several reasons: ambiguous requirements, missing dependencies, test-environment issues, or API rate limits. The orchestrator handles these through a retry mechanism (up to three attempts), but fallback behaviour should also be implemented:

# In your orchestrator, add a failure handler:

def _handle_failure(self, task, stage, error):
    """Handle pipeline failure with escalation."""
    self.notion.append_log(
        task.page_id,
        f"FAILED at {stage}: {error[:300]}"
    )

    # After max retries, reset status and flag for human attention
    self.notion.update_status(task.page_id, "To Do")
    self.notion.update_property(
        task.page_id, "Priority", "Critical",
        prop_type="select"
    )

    # Send notification (Slack webhook example)
    if os.environ.get("SLACK_WEBHOOK_URL"):
        httpx.post(
            os.environ["SLACK_WEBHOOK_URL"],
            json={
                "text": f":warning: Pipeline failed for: {task.title}\n"
                        f"Stage: {stage}\nError: {error[:200]}"
            },
        )

Logging All Interactions to Notion

Every Claude Code interaction should be logged to the task's page in Notion. This creates an audit trail that assists debugging and provides visibility to the whole team. The append_log method in the orchestrator handles this; it adds timestamped entries as paragraph blocks on the task page. For richer logs, code blocks containing Claude Code's full output may be appended:

def append_code_log(self, page_id: str, title: str, content: str):
    """Append a code block log entry to the Notion page."""
    self.client.patch(
        f"/blocks/{page_id}/children",
        json={
            "children": [
                {
                    "object": "block",
                    "type": "heading_3",
                    "heading_3": {
                        "rich_text": [{"type": "text",
                                       "text": {"content": title}}]
                    },
                },
                {
                    "object": "block",
                    "type": "code",
                    "code": {
                        "rich_text": [{"type": "text",
                                       "text": {"content": content[:2000]}}],
                        "language": "plain text",
                    },
                },
            ]
        },
    ).raise_for_status()

Rate-Limiting Notion API Calls

Notion's API enforces a rate limit of three requests per second for integrations. When multiple tasks are processed or many updates issued, this limit may be reached. Simple rate limiting should be added to the client:

import time
from threading import Lock

class RateLimiter:
    def __init__(self, max_per_second: float = 2.5):
        self.min_interval = 1.0 / max_per_second
        self.last_call = 0.0
        self.lock = Lock()

    def wait(self):
        with self.lock:
            now = time.monotonic()
            elapsed = now - self.last_call
            if elapsed < self.min_interval:
                time.sleep(self.min_interval - elapsed)
            self.last_call = time.monotonic()

Handling Concurrent Tasks

If multiple developers (or orchestrator instances) attempt to pick the same task simultaneously, conflicts will arise. Notion's status field should be used as an optimistic lock: before work begins on a task, the status should be re-checked to confirm it is still "To Do." If it has changed, the task should be skipped and the next one selected. In the orchestrator, this involves re-querying the task status before processing:

def process_task(self, task):
    # Re-check status to avoid race conditions
    current = self.notion.get_task(task.page_id)
    if current.status != "To Do":
        logger.info(f"Task '{task.title}' already claimed, skipping")
        return True  # Not a failure, just skip
    # ... proceed with processing

Security Considerations

Automated code generation introduces security considerations that must be addressed before this pipeline is deployed in a production environment.

Store API keys securely. The Notion API key, GitHub tokens, and other credentials should never be hard-coded in source files or configuration. Environment variables loaded from a .env file excluded from version control via .gitignore should be used instead. For production orchestrator deployments, a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or the CI/CD platform's secret storage is appropriate.

Apply least-privilege permissions. The Notion integration should have access only to the specific databases it requires, not the entire workspace. When creating the integration at notion.so/my-integrations, only the necessary capabilities (read, update, insert) should be selected, and only the relevant databases should be shared with the integration.

Never skip human code review. This requirement is non-negotiable. Regardless of Claude Code's quality, every PR should be reviewed by a human before merging. The pipeline deliberately creates PRs and sets the status to "In Review," providing a human checkpoint before code reaches production. The /complete-task command should only be invoked after a human has reviewed and merged the PR.

Audit the generated code. Automated security scanning should be set up in the CI/CD pipeline. Tools such as Bandit (Python), ESLint security plugins (JavaScript), or Semgrep can detect common security issues in generated code before review. This provides a safety net for issues such as SQL injection, hard-coded secrets, or insecure cryptographic practices.

Limit the orchestrator's blast radius. When the orchestrator runs in automated mode, sandboxing it in a container or VM with limited network access is advisable. It should be permitted to reach only the Notion API, the git remote, and the local filesystem. This prevents accidentally generated malicious code from accessing sensitive internal systems.

Comparison with Alternative Stacks

How does the Claude Code and Notion pipeline compare with other popular development-automation stacks? The following comparison is based on real-world experience and community feedback as of early 2026.

The fundamental differentiator for Claude Code is its agentic nature. Copilot and Cursor are reactive — they respond when the developer is typing in an editor. Claude Code is proactive: it receives a task and executes autonomously across files, commands, and external services. This capability makes the pipeline architecture possible. A "task in, PR out" pipeline cannot be built with a code autocompleter.

Practical Tips for Success

The following lessons, drawn from building and iterating on this pipeline, save the most time and prevent the most difficulties.

Begin with a limited scope. Automating everything on the first day is not advisable. Begin with the /pick-task and /submit-task commands to confirm the Notion integration is functioning. Add /work-task once the MCP connection is familiar. Advance to the full orchestrator only after the individual commands prove reliable. Each stage builds confidence in the next.

Always retain a human reviewer. This point cannot be overstated. Claude Code generates excellent code, but it lacks the business context to determine whether a feature solves the right problem. The pipeline should eliminate routine work, not human judgment. The "In Review" status exists for that reason.

Keep CLAUDE.md updated. The CLAUDE.md file is the single most impactful lever for code quality. Whenever a project's conventions, tech stack, or architecture change, CLAUDE.md should be updated. It functions as the onboarding document one would give a senior developer joining the project, because that is effectively what Claude Code reads before every task.

Write detailed Notion task descriptions. The quality of Claude Code's output is directly proportional to the quality of the input. A task stating "add auth" produces generic results. A task with acceptance criteria, edge cases, and links to relevant documentation produces production-ready code. Time invested upfront in clear task descriptions pays substantial dividends.

Use Notion's rollup and formula properties for metrics. Once the pipeline is operational, Notion's built-in analytics can be used to track velocity. A formula property can compute the time between "In Progress" and "Done." Rollups can aggregate tasks per sprint, per developer, or per type. These metrics help measure the degree to which the pipeline accelerates the team.

Monitor API usage. Both the Notion API and Claude Code have rate limits and usage quotas. When the orchestrator runs in continuous watch mode, API call counts should be monitored. The rate limiter in the orchestrator script helps, but unexpected spikes (such as a database containing 50 tasks in "To Do") can still cause issues.

Version-control the command files. The .claude/commands/ directory should be committed to git and treated as part of the project's infrastructure. This ensures that every developer on the team uses the same pipeline commands, and that workflow changes pass through the same PR review process as code changes.

Concluding Observations

This guide has constructed something significant: a complete automated workflow pipeline that connects Notion's flexible project management to Claude Code's agentic coding capabilities. The components now available are summarised below.

Five custom Claude Code commands — /pick-task, /work-task, /submit-task, /doc-task, and /complete-task — manage the entire task lifecycle from selection to completion. Each command both reads from and writes to Notion, producing a bidirectional integration in which the project board is not a passive display but an active component of the development process.

An MCP-powered Notion connection provides Claude Code with native access to the project database without custom API plumbing. A Python orchestrator script can run the pipeline autonomously, with retry logic, error handling, and Notion-based logging. Specialised workflows handle bug fixes, documentation generation, sprint planning, and code review. Database templates can be deployed to Notion with a single API call.

The broader implication concerns the future of software development. The field is moving from a model in which AI assists with individual code completions to one in which AI operates as a team member that can own entire tasks from start to finish. The pipeline constructed here is an early example of this paradigm, and it is sufficiently practical for use today.

One critical qualification deserves emphasis: this pipeline augments human developers; it does not replace them. The human remains in the loop for task definition (what to build), code review (whether it is correct and safe), and strategic decisions (whether it should be built at all). The pipeline eliminates the mechanical overhead of branch creation, status updates, PR formatting, documentation generation, and task bookkeeping — the work that no one enjoys and everyone forgets. Automating it saves not only time but mental energy for the decisions that actually move the product forward.

A practical starting point follows: install Claude Code, create a Notion integration, set up the MCP configuration, and implement /pick-task as the first command. Run it on a real task. Observe the Notion status update automatically. Once that experience has been achieved, the remainder of the pipeline becomes a natural next step. All the elements required are now in place.

References

• Claude Code Documentation—Anthropic
• Model Context Protocol (MCP),Official Specification
• Notion API Documentation—Notion Developers
• Notion MCP Server—GitHub Repository
• Notion API Reference, Databases, Pages, and Blocks
• Claude Code CLI Usage—Non-Interactive Mode
• GitHub CLI (gh) Manual—Pull Request Management
• Developer Time Management Research, Atlassian