Advisor MCP Expert

A Model Context Protocol specialist with deep expertise in creating, configuring, and optimizing MCP server integrations, covering protocol architecture, server implementation, and integration patterns for extending AI assistant capabilities.

When to Use This Agent

Choose Advisor MCP Expert when:

• Building custom MCP servers to extend Claude Code's capabilities
• Integrating external APIs, databases, or services via MCP
• Debugging MCP connection issues, tool registration, or protocol errors
• Designing MCP server architectures for team-wide shared tooling
• Migrating from custom tool implementations to the MCP standard

Consider alternatives when:

• Building general REST APIs unrelated to MCP (use a backend development agent)
• Configuring Claude Code settings without custom tools (use a general Claude agent)
• Working with other AI assistant extension protocols (use the relevant platform agent)

Quick Start

Copy
# .claude/agents/advisor-mcp-expert.yml
name: Advisor MCP Expert
description: Design and implement MCP server integrations
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebSearch

Example invocation:

claude "Create an MCP server that exposes our internal Jira API as tools for creating issues, searching, and updating status"

Core Concepts

MCP Architecture Overview

Component	Role	Example
MCP Host	AI application that uses tools	Claude Code, Claude Desktop
MCP Client	Protocol handler within the host	Built into Claude Code
MCP Server	Provides tools, resources, prompts	Your custom server
Transport	Communication channel	stdio, SSE, HTTP

MCP Server Implementation

Copy
// src/index.ts — Basic MCP server
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'jira-tools',
  version: '1.0.0',
});

// Register a tool
server.tool(
  'create-issue',
  'Create a new Jira issue',
  {
    project: z.string().describe('Jira project key (e.g., PROJ)'),
    summary: z.string().describe('Issue title'),
    description: z.string().optional().describe('Issue description'),
    type: z.enum(['Bug', 'Story', 'Task']).default('Task'),
    priority: z.enum(['Low', 'Medium', 'High', 'Critical']).default('Medium'),
  },
  async ({ project, summary, description, type, priority }) => {
    const issue = await jiraClient.createIssue({
      fields: {
        project: { key: project },
        summary,
        description,
        issuetype: { name: type },
        priority: { name: priority },
      },
    });

    return {
      content: [{
        type: 'text',
        text: `Created issue ${issue.key}: ${issue.self}`,
      }],
    };
  }
);

// Register a resource
server.resource(
  'jira-project',
  'jira://project/{key}',
  async (uri) => {
    const key = uri.pathname.split('/').pop();
    const project = await jiraClient.getProject(key);
    return {
      contents: [{
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(project, null, 2),
      }],
    };
  }
);

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Claude Code Configuration

Copy
// .claude/settings.json
{
  "mcpServers": {
    "jira-tools": {
      "command": "node",
      "args": ["./mcp-servers/jira-tools/dist/index.js"],
      "env": {
        "JIRA_URL": "https://mycompany.atlassian.net",
        "JIRA_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

Configuration

Parameter	Description	Default
transport	Communication transport (stdio, sse, http)	stdio
sdk_version	MCP SDK version	latest
auth_method	Authentication approach (env, oauth, api-key)	env
error_handling	Error response strategy (detailed, safe, minimal)	safe
logging	Server logging level (debug, info, warn, error)	info
rate_limiting	Request rate limiting configuration	none

Best Practices

1. Use descriptive tool names and parameter descriptions. The AI model selects which tool to call based on the name and description. A tool named create-issue with parameters described as "Jira project key (e.g., PROJ)" is far more likely to be called correctly than ci with a parameter called p. Include examples in descriptions and use Zod's .describe() for every parameter.

2. Validate all inputs at the MCP server boundary. Even though Zod schemas provide basic validation, add business logic validation inside the handler: verify that project keys exist, check user permissions, and validate cross-field dependencies. Return clear error messages that help the AI understand what went wrong and how to fix the invocation.

3. Return structured, parseable responses. Include relevant identifiers (issue key, URL), status information, and next-step suggestions in tool responses. A response like "Created PROJ-123. View at https://jira.com/PROJ-123. To assign it, use the update-issue tool." gives the AI context to continue the workflow without asking the user for information the tool already provided.

4. Handle errors gracefully with actionable error messages. When a Jira API call fails, do not return the raw HTTP error. Translate it: "Project 'INVALID' not found. Available projects: PROJ, CORE, WEB." This lets the AI self-correct on the next attempt. Distinguish between user-correctable errors (wrong project key) and system errors (Jira is down) with different response formats.

5. Implement proper environment variable management for secrets. Never hardcode API tokens, passwords, or URLs in the MCP server code. Use environment variables injected through the Claude Code settings file. Support both direct values and variable references (${JIRA_API_TOKEN}). Document required environment variables in the server's README with setup instructions.

Common Issues

MCP server fails to start with "connection refused" or "spawn error". The most common cause is an incorrect command or args path in the settings file. Verify the path is absolute or correctly relative. Check that Node.js is in the PATH, that the built JavaScript file exists (run npm run build first), and that file permissions allow execution. Test the server manually with node ./dist/index.js before configuring Claude Code.

Tools are registered but Claude does not use them. Claude selects tools based on relevance to the user's request. If tool names and descriptions are too generic or do not match the user's language, they will not be selected. Make tool names action-oriented and descriptions specific: "Search Jira issues by JQL query and return matching issue keys, summaries, and statuses" is more discoverable than "Query Jira." Test by explicitly asking Claude to use the tool.

Server crashes with unhandled promise rejections from external API calls. MCP tool handlers that make HTTP calls to external services must catch all errors. An unhandled rejection crashes the entire MCP server process, breaking all tools — not just the one that failed. Wrap every async operation in try/catch and return error responses instead of throwing. Implement connection retry logic for transient failures.