MCP: Build & Manage Protocol Servers

Build MCP servers that integrate APIs, and execute tools from configured servers.

When to Use

Building: Create MCP servers (Python/TypeScript), integrate APIs, design agent-centric tools, implement validation/error handling, create evaluations

Managing: Discover/execute tools via Gemini CLI, filter tools for tasks, manage multi-server configs

Core Concepts

MCP = standardized protocol for AI agents to access external tools/data.

Components: Tools (executable functions), Resources (read-only data), Prompts (templates) Transports: Stdio (local), HTTP (remote), SSE (real-time)

Load: references/protocol-basics.md for full protocol details

Part 1: Building MCP Servers

Build high-quality MCP servers that enable LLMs to accomplish real-world tasks.

Development Workflow

Phase 1: Research & Planning

• Study agent-centric design principles (workflows over endpoints)

• Research target API documentation exhaustively

• Load framework documentation (Python SDK or TypeScript SDK)

• Plan tool selection, shared utilities, input/output design, error handling

Phase 2: Implementation

• Set up project structure (single file for Python, full structure for TypeScript)

• Implement core infrastructure (API clients, error handlers, formatters)

• Register tools with proper schemas and annotations

• Follow language-specific best practices

Phase 3: Testing & Quality

• Code quality review (DRY, composability, consistency)

• Run builds and syntax checks

• Use quality checklists

Phase 4: Evaluation

• Create 10 complex, realistic evaluation questions

• Questions must be read-only, independent, and verifiable

• Test LLM's ability to use your server effectively

Reference: references/building-servers.md

• Load for complete development guide with:

• Agent-centric design principles

• Python (FastMCP) implementation guide with Pydantic models

• TypeScript (MCP SDK) implementation guide with Zod schemas

• Tool naming conventions, response formats, pagination patterns

• Character limits, error handling, security best practices

• Complete working examples and quality checklists

• Evaluation creation and testing methodology

Key Best Practices

Tool Design:

• Use service-prefixed names (slack_send_message , not send_message )

• Support both JSON and Markdown response formats

• Implement pagination with limit , offset , has_more

• Set CHARACTER_LIMIT constant (typically 25,000)

• Provide actionable error messages that guide agents

Code Quality:

• Extract common functionality into reusable functions

• Use async/await for all I/O operations

• Type hints (Python) or strict TypeScript throughout

• Comprehensive docstrings with explicit schemas

Reference: references/best-practices.md

• Load for comprehensive guidelines

Part 2: Using MCP Tools

Execute and manage tools from configured MCP servers efficiently.

Configuration

MCP servers configured in .claude/.mcp.json :

{ "mcpServers": { "server-name": { "command": "npx", "args": ["-y", "package-name"], "env": {"API_KEY": "${ENV_VAR}"} } } }

Gemini CLI Integration: Create symlink for shared config:

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

Reference: references/using-tools.md

• Load for complete configuration and usage guide

Execution Methods (Priority Order)

1. Gemini CLI (Primary)

Automatic tool discovery and execution via natural language.

CRITICAL: Use stdin piping, NOT -p flag (deprecated, skips MCP init)

echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash

Benefits:

• Automatic tool discovery and selection

• Structured JSON responses (if GEMINI.md configured)

• Fastest execution

• No manual tool specification needed

GEMINI.md Response Format: Place in project root to enforce JSON-only responses:

Gemini CLI Instructions

Always respond in this exact JSON format: {"server":"name","tool":"name","success":true,"result":<data>,"error":null} Maximum 500 characters. No markdown, no explanations.

2. Direct CLI Scripts (Secondary)

Manual tool specification when you know exact server/tool needed:

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

3. mcp-manager Subagent (Fallback)

Delegate to subagent when Gemini unavailable or for complex multi-tool workflows.

Reference: references/using-tools.md

• Load for:

• Complete Gemini CLI guide with examples

• Direct script usage and options

• Subagent delegation patterns

• Tool discovery and filtering strategies

• Multi-server orchestration

• Troubleshooting and debugging

Tool Discovery

List available tools to understand capabilities:

Saves to assets/tools.json for offline reference

npx tsx scripts/cli.ts list-tools

List prompts and resources

npx tsx scripts/cli.ts list-prompts npx tsx scripts/cli.ts list-resources

Intelligent Selection: LLM reads assets/tools.json directly for context-aware tool filtering (better than keyword matching).

Quick Start Examples

Building a Server

Python:

from mcp.server.fastmcp import FastMCP from pydantic import BaseModel, Field

mcp = FastMCP("github_mcp")

class SearchInput(BaseModel): query: str = Field(..., min_length=2, max_length=200) limit: int = Field(default=20, ge=1, le=100)

@mcp.tool(name="github_search_repos", annotations={"readOnlyHint": True}) async def search_repos(params: SearchInput) -> str: # Implementation pass

if name == "main": mcp.run()

TypeScript:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod";

const server = new McpServer({name: "github-mcp-server", version: "1.0.0"});

const SearchSchema = z.object({ query: z.string().min(2).max(200), limit: z.number().int().min(1).max(100).default(20) }).strict();

server.registerTool("github_search_repos", { description: "Search GitHub repositories", inputSchema: SearchSchema, annotations: {readOnlyHint: true} }, async (params) => { // Implementation });

Load references/building-servers.md for complete implementation guides.

Using Tools

Gemini CLI:

IMPORTANT: Use stdin piping, NOT -p flag

echo "Search GitHub for MCP servers and summarize top 3" | gemini -y -m gemini-2.5-flash

Direct Script:

npx tsx scripts/cli.ts call-tool github search_repos '{"query":"mcp","limit":3}'

Load references/using-tools.md for complete usage patterns.

Reference Files

Load these as needed during your work:

Core References

references/building-servers.md

• Complete MCP server development guide

• Agent-centric design principles

• Python (FastMCP) and TypeScript (MCP SDK) implementation

• Tool patterns, response formats, pagination, error handling

• Complete examples and quality checklists

• Evaluation creation methodology

references/using-tools.md

• Complete MCP tool execution guide

• Gemini CLI integration and configuration

• Direct script execution patterns

• Subagent delegation strategies

• Tool discovery and filtering

• Multi-server orchestration

references/best-practices.md

• Universal MCP guidelines

• Server and tool naming conventions

• Response format standards (JSON vs Markdown)

• Pagination, character limits, truncation

• Security and privacy considerations

• Testing and compliance requirements

Supporting References

• references/protocol-basics.md

• JSON-RPC protocol details

• references/python-guide.md

• Python/FastMCP specifics (Pydantic models, async patterns)

• references/typescript-guide.md

• TypeScript/Zod specifics (strict types, project structure)

• references/evaluation-guide.md

• Creating effective MCP server evaluations

Progressive Disclosure

This SKILL.md provides high-level overview. Load reference files when:

Building Servers:

• Starting implementation → Load references/building-servers.md

• Need language-specific details → Load references/python-guide.md or references/typescript-guide.md

• Creating evaluations → Load references/evaluation-guide.md

Using Tools:

• Setting up Gemini CLI → Load references/using-tools.md

• Debugging tool execution → Load references/using-tools.md

• Multi-server configuration → Load references/using-tools.md

Best Practices:

• Reviewing standards → Load references/best-practices.md

• Security considerations → Load references/best-practices.md

Integration Patterns

Build + Use: Create MCP server, then test with Gemini CLI Multi-Server: Configure multiple servers, orchestrate via Gemini CLI Evaluation-Driven: Build server, create evaluations, iterate based on LLM feedback

Boundaries

Will:

• Guide MCP server development in Python or TypeScript

• Provide tool execution strategies via Gemini CLI or scripts

• Ensure best practices for agent-centric design

• Help create effective evaluations

• Configure multi-server setups

Will Not:

• Run long-running server processes in main thread (use tmux or evaluation harness)

• Skip input validation or error handling

• Create tools without comprehensive documentation

• Build servers without considering agent context limits