Integration: External Tools (MCP Servers)

Relevant source files

The following files were used as context for generating this wiki page:

• .mcp.json
• README.md
• CLAUDE.md
• .claude/settings.json
• .claude/commands/ticket.md

MCP (Model Context Protocol) servers are a core feature that allows Claude Code to connect with and control external tools and services. They act as local bridges, providing Claude with a set of tools to interact with third-party APIs like JIRA, GitHub, Slack, and databases. This integration enables powerful, automated workflows that span from ticket management to code implementation and status updates.

For example, an MCP integration with JIRA allows Claude to read a ticket's requirements, implement the feature, update the ticket's status, and create a pull request linked back to the original ticket, all driven by a single command like /ticket PROJ-123. This transforms Claude from a code generator into a task-oriented assistant capable of managing entire development lifecycles.

Sources: README.md:29-32, 126-130, 173-175, .claude/commands/ticket.md

Architecture and Data Flow

MCP servers run as local processes that Claude Code communicates with. The server acts as an intermediary, translating Claude's tool requests into API calls to the external service and returning the results.

Sources: README.md:131-135

This diagram illustrates the basic communication flow between Claude, the MCP server, and the external API.

Configuration

MCP server integrations are defined in the .mcp.json file located in the project root. This file is intended to be committed to the repository so the entire team can share the same tool integrations.

Sources: README.md:128-129

.mcp.json Format

The mcpServers object contains a key for each configured server. Each server configuration specifies how to run the server process and provide it with the necessary environment variables for authentication.

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Sources: README.md:137-145

The fields for each server configuration are detailed below:

Field	Required	Description
type	Yes	The server type. Supported values are stdio for a local process or http for a remote server.
command	For stdio	The executable command to run the server (e.g., npx, python).
args	No	An array of command-line arguments to pass to the executable.
env	No	An object of environment variables to set for the server process. It supports ${VAR} expansion.
url	For http	The URL of the remote MCP server.
headers	For http	An object of HTTP headers to send for authentication with a remote server.

Sources: README.md:146-154

Enabling MCP Servers in settings.json

After defining servers in .mcp.json, you must enable them in .claude/settings.json. You can either enable all defined servers or approve specific ones by name.

To enable all servers from .mcp.json:

{
  "enableAllProjectMcpServers": true
}

To enable a specific list of servers:

{
  "enabledMcpjsonServers": ["jira", "github", "slack"]
}

Sources: README.md:238-246, .claude/settings.json:2

Environment Variables

MCP server configurations use variable expansion (${VAR}) to securely pass secrets like API tokens to the server process. These variables must be set in your shell environment (e.g., in a .env file or your shell profile) and should not be committed to the repository.

• ${VAR}: Expands to the value of the environment variable VAR. The process will fail if the variable is not set.
• ${VAR:-default}: Uses a default value if the VAR environment variable is not set.

Example of setting required variables for JIRA integration:

export JIRA_HOST="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="your-api-token"

Sources: README.md:226-236

Common Server Configurations

The repository provides examples for integrating with various services. These snippets from .mcp.json demonstrate how to configure connections to issue trackers, DevOps tools, communication platforms, and databases.

Sources: .mcp.json:2-45

Service Category	Configuration Snippet
Issue Tracking	json { "jira": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-jira"], "env": { "JIRA_HOST": "${JIRA_HOST}", "JIRA_EMAIL": "${JIRA_EMAIL}", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}" } }, "linear": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-linear"], "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" } } }
Code & DevOps	json { "github": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }, "sentry": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-sentry"], "env": { "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}", "SENTRY_ORG": "${SENTRY_ORG}" } } }
Communication	json { "slack": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-slack"], "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}", "SLACK_TEAM_ID": "${SLACK_TEAM_ID}" } } }
Databases	json { "postgres": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-postgres"], "env": { "DATABASE_URL": "${DATABASE_URL}" } } }

Sources: README.md:192-224, .mcp.json:2-45

Example Workflow: JIRA Ticket Automation

The power of MCP servers is best illustrated through a complete workflow. The /ticket command demonstrates how a JIRA integration can automate the development process from start to finish.

Sources: README.md:173-175, .claude/commands/ticket.md

The following sequence diagram shows the steps Claude takes after a user invokes /ticket PROJ-123.

This workflow highlights how MCP integrations enable Claude to:

1. Fetch requirements from an external system.
2. Perform file system and version control operations.
3. Implement code changes.
4. Update the external system with progress.
5. Integrate with other tools like GitHub to finalize the task.

Sources: README.md:170-172, CLAUDE.md:21-23

Summary

MCP servers are a critical component for extending Claude Code's capabilities beyond the local file system. By defining simple JSON configurations in .mcp.json, developers can grant Claude access to a wide range of external services, enabling the automation of complex, multi-step development and project management workflows. This integration is key to leveraging Claude as a highly effective, automated engineering assistant.

Sources: README.md:126-130