MCP Patterns

MCP Server Development Patterns

Development patterns for building MCP (Model Context Protocol) servers with the You.com MCP package.

For end users: See packages/mcp/README.md for setup and usage. For universal patterns: See .claude/rules/code-patterns.md

When to Use This Skill

Use this skill when:

• Developing or contributing to @youdotcom-oss/mcp package
• Implementing MCP tools and utilities
• Debugging MCP server issues
• Understanding MCP-specific patterns and conventions

Tech Stack

• Runtime: Bun >= 1.2.21 (not Node.js)
• MCP SDK: @modelcontextprotocol/sdk ^1.24.3
• Validation: Zod ^4.1.13
• HTTP Transport: Hono ^4.10.7 with Bearer token auth
• Testing: Bun test (built-in test runner)
• Code Quality: Biome 2.3.8 (linter + formatter)

Quick Start

cd packages/mcp

# Install dependencies (from monorepo root)
cd ../..
bun install

# Set up API key
echo "export YDC_API_KEY=your-actual-api-key-here" > .env
source .env

# From package directory
cd packages/mcp
bun run dev                    # Start stdio server
bun start                      # Start HTTP server on port 4000
bun test                       # Run tests
bun run check                  # Run all checks

MCP-Specific Patterns

Schema Design with Zod

All MCP tool inputs and API responses must use Zod schemas:

// ✅ Use .describe() for documentation (shows in MCP inspector)
export const SearchQuerySchema = z.object({
  query: z.string().describe('Search query string'),
  count: z.number().int().min(1).max(20).default(10).describe('Number of results'),
});

// ✅ Validate API responses
const response = SearchApiResponseSchema.parse(await apiCall());

Why this pattern?

• .describe() provides human-readable documentation in MCP inspector
• Zod validation catches API response format changes early
• Type safety ensures tool inputs match expected schema

Error Handling

MCP tools must NEVER throw errors - always return error messages:

// ✅ Correct - return error as content
try {
  const result = await apiCall();
  return { content: [{ type: 'text', text: result }] };
} catch (err: unknown) {
  const error = err instanceof Error ? err.message : String(err);
  return {
    content: [{ type: 'text', text: `Error: ${error}` }],
    isError: true
  };
}

// ❌ Wrong - throwing breaks MCP protocol
throw new Error('API failed');

Why this pattern?

• MCP protocol expects all tool calls to return responses
• Throwing errors breaks the client-server connection
• isError: true flag allows clients to handle errors gracefully

Logging

Use getLogger(mcp) for MCP server notifications, NEVER console.log:

// ✅ Correct - MCP notifications
const log = getLogger(mcp);
log('Calling You.com API');

// ❌ Wrong - bypasses MCP protocol
console.log('Calling You.com API');

Why this pattern?

• MCP clients expect structured notifications via protocol
• console.log outputs to stdout, interfering with stdio transport
• getLogger() properly routes messages through MCP notification system

Response Format

All MCP tools must return both content and structuredContent:

return {
  content: [
    { type: 'text', text: 'User-readable summary' }
  ],
  structuredContent: {
    results: [...], // Structured data
    metadata: {...}
  }
};

Why this pattern?

• content provides human-readable text for display
• structuredContent enables programmatic processing by clients
• Both formats serve different use cases

MCP Inspector

Test and debug MCP tools interactively:

bun run inspect  # Automatically loads .env variables

Why this tool?

• Interactive testing without writing test code
• Visual inspection of tool schemas and responses
• Quick validation of changes during development

Testing

MCP-Specific Testing: Shared vs Dedicated Clients

Long-running tests with retries may disconnect shared MCP clients from beforeAll. Use dedicated clients for isolated tests:

// ✅ Dedicated client for long-running or isolated tests
test.serial('memory test', async () => {
  const stdioPath = Bun.resolveSync('../../bin/stdio', import.meta.dir);
  const transport = new StdioClientTransport({
    command: 'npx',
    args: [stdioPath],
    env: { YDC_API_KEY },
  });

  const memoryClient = new Client({
    name: 'memory-test-client',
    version: '1.0.0',
  });

  await memoryClient.connect(transport);
  await memoryClient.callTool(/* ... */);
  await memoryClient.close();
}, { timeout: 15_000 });

When to use:

• Shared client: Quick tests (<30s), no retry, basic integration tests
• Dedicated client: Long tests (>30s), tests with retry, performance tests

See src/tests/processing-lag.spec.ts for complete example.

Architecture

Request Flow

Stdio Transport (Local Development):

1. MCP Client → stdin → stdio.ts → MCP Server → You.com API → stdout → MCP Client

HTTP Transport (Remote Deployment):

1. MCP Client → SSE (/mcp) → http.ts (Bearer auth) → MCP Server → You.com API → SSE → MCP Client

Core Files

• src/stdio.ts - Stdio transport entry point
• src/http.ts - HTTP transport with Bearer token auth, /mcp (SSE), /mcp-health
• src/get-mcp-server.ts - MCP server factory
• src/*/register-*-tool.ts - Tool registration
• src/*/*.schemas.ts - Zod schemas
• src/*/*.utils.ts - API calls, formatting
• src/utils.ts - Public API export for library consumers

Troubleshooting

YDC_API_KEY not found

echo "export YDC_API_KEY=your-actual-api-key-here" > .env
source .env
echo $YDC_API_KEY  # Verify it's set

Test Failures with API Rate Limits

Symptom: Tests fail with 429 (Too Many Requests)

Solution:

• Wait a few minutes before re-running tests
• Run specific test suites instead of all at once
• Use bun test --bail to stop after first failure
• Check rate limits at api.you.com

MCP Client Connection Issues (Stdio)

# Verify server starts
bun run dev

# Check API key is set
echo $YDC_API_KEY

MCP Client Connection Issues (HTTP)

# Verify server starts on port 4000
bun start

# Test health endpoint
curl http://localhost:4000/mcp-health

# Test with valid Bearer token
curl -H "Authorization: Bearer your-key-here" \
  http://localhost:4000/mcp

Publishing

For standard publishing process: See root AGENTS.md

MCP-Specific Deployment

After npm publish, this package triggers:

1. Remote Deployment (via repository_dispatch):

   • update-mcp-version event to deployment repository
   • Stable releases: deploy-mcp-production after version update completes
   • Prereleases skip production deployment

2. Anthropic MCP Registry (stable releases only):

   • Auto-updates server.json versions
   • Makes server discoverable at io.github.youdotcom-oss/mcp
   • Runs after successful production deployment

Workflow: .github/workflows/publish-mcp.yml

Related Skills

• .claude/rules/code-patterns.md - Universal code patterns
• .claude/rules/git-workflow.md - Git conventions
• .claude/skills/documentation - Documentation standards

Contributing

See root AGENTS.md and CONTRIBUTING.md for guidelines.

Package scope: Use mcp in commit messages:

feat(mcp): add new search filter
fix(mcp): resolve timeout issue