Integration Patterns: Connecting Claude Code with External Tools and Services#

                    ┌──────────────────────────────────┐
                    │          GitHub Events           │
                    │   (PR, issue, push, schedule)    │
                    └──────────────┬───────────────────┘
                                   │
                                   ▼
┌─────────────┐    ┌──────────────────────────────────┐
│  Your       │───▶│         Claude Code              │
│  Scripts    │    │                                  │
│  (claude -p)│    │  ┌────────┐    ┌──────────────┐  │
└─────────────┘    │  │ Hooks  │    │  MCP Servers │  │
                   │  │ (auto) │    │  (on demand) │  │
                   │  └───┬────┘    └─────┬────────┘  │
                   │      │               │           │
                   └──────┼───────────────┼───────────┘
                          │               │
                          ▼               ▼
                    ┌────────────┐  ┌──────────────┐
                    │ Local      │  │ External     │
                    │ Scripts    │  │ Services     │
                    │ (lint,     │  │ (GitHub,     │
                    │  format,   │  │  Sentry,     │
                    │  test)     │  │  Postgres,   │
                    └────────────┘  │  Notion...)  │
                                    └──────────────┘

# HTTP (recommended for remote servers)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# stdio (for local processes)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/mydb"

# Local scope (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Project scope (shared via git)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# User scope (available across all projects)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

# Add the server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Authenticate (opens browser for OAuth flow)
# Type /mcp in Claude Code, then select "Authenticate"

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# Then in Claude Code:
# "What's our total revenue this month?"
# "Show me the schema for the orders table"

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# "Review PR #456 and suggest improvements"
# "Create a new issue for the bug we just found"

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# "What are the most common errors in the last 24 hours?"
# "Which deployment introduced these new errors?"

# Reference an issue directly
> Can you analyze @github:issue://123 and suggest a fix?

# Compare across sources
> Compare @postgres:schema://users with @docs:file://database/user-model

SessionStart ──▶ UserPromptSubmit ──▶ PreToolUse ──▶ [tool executes]
                                                          │
                  Stop ◀── PostToolUse/PostToolUseFailure ◀┘
                   │
                   ▼
              SessionEnd

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete: $ARGUMENTS",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-dangerous.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked"
    }
  }'
else
  exit 0
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/run-tests.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/load-context.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/setup-env.sh
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG=true' >> "$CLAUDE_ENV_FILE"
fi
exit 0

{
  "type": "command",
  "command": ".claude/hooks/run-tests.sh",
  "async": true,
  "timeout": 300
}

# Simple query
claude -p "Generate a .gitignore for a Go project"

# Process piped input
cat src/utils.ts | claude -p "Find potential bugs"

# Reference files with @
claude -p "Refactor @src/api/auth.ts to use async/await"

# Get structured JSON output
claude -p "List all TODO comments in the codebase" --output-format json

# Stream results for real-time display
claude -p "Refactor auth module" --output-format stream-json

claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
  "Find bugs in @src/auth.ts"

# Add rules while keeping Claude Code defaults (recommended)
claude -p --append-system-prompt "Always use TypeScript" "Review this file"

# Load custom rules from a file
claude -p --append-system-prompt-file ./prompts/review-rules.txt "Review this PR"

# Complete prompt replacement (loses Claude Code defaults)
claude -p --system-prompt "You are a security auditor" "Audit @src/auth.ts"

# Analyze test output
go test ./... 2>&1 | claude -p "Explain these test failures"

# Review a diff
git diff main | claude -p "Review these changes for bugs"

# Process multiple files
find . -name "*.go" -newer go.sum | \
  xargs cat | \
  claude -p "Find any Go 1.22 features in these recently modified files"

# Chain Claude invocations
claude -p "Find all API endpoints in @src/" --output-format json | \
  claude -p "Generate OpenAPI docs for these endpoints"

# Constrained automation: limited turns, specific tools, capped budget
claude -p \
  --max-turns 5 \
  --max-budget-usd 2.00 \
  --allowedTools "Read" "Grep" "Glob" \
  --model sonnet \
  "Find all functions that handle authentication"

export CLAUDE_CODE_API_KEY="sk-ant-..."
claude -p "Review this codebase for security issues"

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

# In Claude Code terminal
/install-github-app

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "/review"
          claude_args: "--max-turns 5"

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"

claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929"

claude mcp serve

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Need Claude to access an external service?
  YES ──▶ MCP server
  NO  ──▼

Need something to run automatically during Claude's work?
  YES ──▶ Hook
  NO  ──▼

Need to call Claude from a script or pipeline?
  YES ──▶ Headless mode (claude -p)
  NO  ──▼

Need Claude to respond to GitHub events?
  YES ──▶ GitHub Actions
  NO  ──▼

Need to package multiple integrations for a team?
  YES ──▶ Plugin

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__db__.*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-query.sh"
          }
        ]
      }
    ]
  }
}

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "/review"
    claude_args: "--max-turns 5 --model sonnet"

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Run the test suite and verify all tests pass. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

## Error Investigation

When investigating production errors, always check Sentry first
using the sentry MCP server before looking at logs.

Bad:  Building an MCP server to run linters after file edits
      (Claude has to decide to call it)

Good: A PostToolUse hook that auto-runs linters on Write|Edit
      (runs automatically, no Claude decision needed)

Bad:  claude -p "Fix all the bugs in this codebase"
      (could run indefinitely, consuming unlimited tokens)

Good: claude -p --max-turns 10 --max-budget-usd 5.00 \
        "Fix the authentication bug in @src/auth.ts"
      (bounded scope, bounded cost)

Bad:  A PostToolUse hook that runs the full test suite
      synchronously after every file write
      (Claude waits minutes between each edit)

Good: The same hook with "async": true
      (Claude continues working, test results arrive later)

Bad:  .mcp.json with "Authorization": "Bearer sk-ant-abc123..."
      (committed to git, visible to everyone)

Good: .mcp.json with "Authorization": "Bearer ${API_KEY}"
      (credentials in local environment)

Bad:  A PreToolUse hook with no matcher that runs
      on every single tool call
      (adds latency to reads, searches, everything)

Good: A PreToolUse hook with matcher "Bash" that only
      checks shell commands
      (runs only when relevant)