openclaw/1kalin/afrexai-mcp-engineering

MCP Engineering — Complete Model Context Protocol System

Build, integrate, secure, and scale MCP servers and clients. From first server to production multi-tool architecture.

When to Use

• Building an MCP server (any language)
• Integrating MCP tools into an AI agent
• Debugging MCP connection/auth issues
• Designing multi-server architectures
• Securing MCP endpoints for production
• Evaluating which MCP servers to use

---

Phase 1: MCP Fundamentals

What MCP Is

Model Context Protocol = standardized way for AI agents to call external tools. Think of it as "USB for AI" — one protocol, any tool.

Architecture

Agent (Client) ←→ MCP Transport ←→ MCP Server ←→ External Service
                   (stdio/HTTP)      (your code)    (API, DB, file system)

Core Concepts

| Concept | What It Does | Example | |---------|-------------|---------| | Server | Exposes tools, resources, prompts | A server wrapping the GitHub API | | Client | Discovers and calls server capabilities | OpenClaw, Claude Desktop, Cursor | | Tool | A callable function with typed params | create_issue(title, body, labels) | | Resource | Read-only data the agent can access | file://workspace/config.json | | Prompt | Reusable prompt templates | summarize_pr(pr_url) | | Transport | How client↔server communicate | stdio (local) or HTTP+SSE (remote) |

Transport Decision

| Factor | stdio | HTTP/SSE | Streamable HTTP | |--------|-------|----------|-----------------| | Setup complexity | Low | Medium | Medium | | Multi-client | No | Yes | Yes | | Remote access | No | Yes | Yes | | Streaming | Via stdio | SSE | Native | | Auth needed | No (local) | Yes | Yes | | Best for | Local dev, single agent | Production, shared | Modern production |

Rule: Start with stdio for development. Move to HTTP for production or multi-agent.

---

Phase 2: Building Your First MCP Server

Server Brief YAML

server_name: "[service]-mcp"
description: "[What this server does in one sentence]"
transport: stdio | http
tools:
  - name: "[verb_noun]"
    description: "[What it does — be specific for LLM tool selection]"
    params:
      - name: "[param]"
        type: "string | number | boolean | object | array"
        required: true | false
        description: "[What this param controls]"
    returns: "[What the tool returns]"
    error_cases:
      - "[When/how it fails]"
resources:
  - uri: "[protocol://path]"
    description: "[What data this exposes]"
external_dependencies:
  - "[API/service this wraps]"
auth_required: true | false
auth_method: "api_key | oauth2 | none"

TypeScript Server Template (stdio)

// server.ts — minimal 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: "my-service",
  version: "1.0.0",
});

// Define a tool
server.tool(
  "get_item",                          // tool name (verb_noun)
  "Fetch an item by ID",               // description (LLM reads this)
  { id: z.string().describe("Item ID") }, // params with descriptions
  async ({ id }) => {
    try {
      const result = await fetchItem(id);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error: ${error.message}` }],
        isError: true,
      };
    }
  }
);

// Define a resource
server.resource(
  "config",
  "config://app",
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(config) }],
  })
);

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

Python Server Template (stdio)

# server.py — minimal MCP server
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import json

server = Server("my-service")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_item",
            description="Fetch an item by ID",
            inputSchema={
                "type": "object",
                "properties": {
                    "id": {"type": "string", "description": "Item ID"}
                },
                "required": ["id"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_item":
        result = await fetch_item(arguments["id"])
        return [TextContent(type="text", text=json.dumps(result, indent=2))]
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write, server.create_initialization_options())

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Tool Design Rules

1. Verb-noun naming: create_issue, search_docs, update_config — never issue or doStuff
2. Descriptions are critical: The LLM picks tools based on descriptions. Be specific. Include when NOT to use.
3. Granular over god-tools: search_issues + get_issue + create_issue beats manage_issues
4. Return structured data: JSON over prose. Let the LLM format for the user.
5. Error messages for LLMs: Include what went wrong AND what to try next
6. Idempotent where possible: create_or_update > create (prevents duplicates from retries)
7. Limit output size: Paginate or truncate. A 10MB response kills the context window.
8. Include examples in descriptions: "Search issues. Example: search_issues(query='bug label:critical')"

Tool Description Quality Checklist

• [ ] Says what the tool DOES (not just the name restated)
• [ ] Mentions when to use vs. when NOT to use
• [ ] Each param has a description with format hints
• [ ] Return format is documented
• [ ] Edge cases mentioned (empty results, not found, etc.)

---

Phase 3: HTTP Transport & Production Server

HTTP Server Template (TypeScript)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

const server = new McpServer({ name: "my-service", version: "1.0.0" });
// ... register tools ...

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport("/mcp", res);
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(3001, () => console.log("MCP server on :3001"));

Auth Patterns

API Key (simplest)

// Middleware
function authMiddleware(req, res, next) {
  const key = req.headers["x-api-key"] || req.headers.authorization?.replace("Bearer ", "");
  if (!key || !validKeys.has(key)) {
    return res.status(401).json({ error: "Invalid API key" });
  }
  req.userId = keyToUser.get(key);
  next();
}

OAuth 2.0 (for user-scoped access)

# MCP OAuth flow
1. Client requests tool → server returns 401 with auth URL
2. User completes OAuth in browser → gets access token
3. Client stores token, includes in subsequent requests
4. Server validates token, calls external API on user's behalf

Production Checklist

• [ ] Rate limiting per client/key
• [ ] Request validation (schema check before execution)
• [ ] Structured logging (request ID, tool name, latency, status)
• [ ] Health check endpoint (/health)
• [ ] Graceful shutdown (finish in-flight requests)
• [ ] Timeout on external calls (don't let tools hang forever)
• [ ] Output size limits (truncate large responses)
• [ ] Error categorization (4xx client vs 5xx server)
• [ ] CORS if browser clients connect
• [ ] TLS in production (always HTTPS)

---

Phase 4: Client Integration

OpenClaw Configuration

# In openclaw config — stdio server
mcpServers:
  my-service:
    command: "node"
    args: ["path/to/server.js"]
    env:
      API_KEY: "{{env.MY_SERVICE_API_KEY}}"

# HTTP server
mcpServers:
  my-service:
    url: "https://mcp.myservice.com/mcp"
    headers:
      Authorization: "Bearer {{env.MY_SERVICE_TOKEN}}"

Claude Desktop Configuration

{
  "mcpServers": {
    "my-service": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Client-Side Tool Selection

When multiple MCP servers are connected, the agent sees ALL tools. Help the agent pick correctly:

1. Unique tool names: Prefix if needed (github_search vs jira_search)
2. Clear descriptions: Disambiguate similar tools across servers
3. Don't overload: 20-30 tools max across all servers. Beyond that, agents get confused.

Multi-Server Architecture

Agent
├── github-mcp (code: create_pr, search_code, list_issues)
├── slack-mcp (comms: send_message, search_messages)
├── postgres-mcp (data: query, list_tables)
└── internal-mcp (business: get_customer, update_pipeline)

Principle: One server per domain. Don't build a mega-server.

---

Phase 5: Testing MCP Servers

Test Pyramid

        /  E2E  \        Agent actually uses the tool
       / Integration \    Tool calls real API (sandbox)
      /    Unit       \   Business logic without MCP layer

Unit Test Pattern

// Test the tool handler directly, no MCP transport
describe("get_item", () => {
  it("returns item when found", async () => {
    mockDb.findById.mockResolvedValue({ id: "123", name: "Test" });
    const result = await getItemHandler({ id: "123" });
    expect(result.content[0].text).toContain("Test");
  });

  it("returns error for missing item", async () => {
    mockDb.findById.mockResolvedValue(null);
    const result = await getItemHandler({ id: "missing" });
    expect(result.isError).toBe(true);
  });

  it("handles API timeout gracefully", async () => {
    mockDb.findById.mockRejectedValue(new Error("timeout"));
    const result = await getItemHandler({ id: "123" });
    expect(result.isError).toBe(true);
    expect(result.content[0].text).toContain("try again");
  });
});

Integration Test with MCP Inspector

# Use the MCP Inspector to manually test
npx @modelcontextprotocol/inspector node server.js

# Or use mcporter for CLI testing
mcporter call my-service.get_item id=123
mcporter list my-service --schema  # verify tool schemas

Test Checklist Per Tool

• [ ] Happy path returns expected format
• [ ] Missing required params returns clear error
• [ ] Invalid param types return clear error
• [ ] Not-found cases handled (don't throw, return error content)
• [ ] Rate limit / quota exceeded handled
• [ ] Auth failure handled (expired token, invalid key)
• [ ] Large response truncated appropriately
• [ ] Timeout handled (external API slow)
• [ ] Concurrent calls don't interfere

---

Phase 6: Common MCP Server Patterns

1. API Wrapper (most common)

Wrap an existing REST/GraphQL API as MCP tools.

External API → MCP Server → Agent

Key decisions:

• Map 1 API endpoint → 1 MCP tool (usually)
• Simplify params (agent doesn't need every API option)
• Aggregate related calls (e.g., get user + get user's repos = 1 tool)
• Cache where safe (reduce API calls)

2. Database Query

Database → MCP Server → Agent

Safety rules:

• Read-only by default. Write tools require explicit opt-in.
• Parameterized queries only. NEVER interpolate agent input into SQL.
• Row limit on all queries (agent can ask for more if needed).
• Schema as a resource (let agent discover tables/columns).

3. File System

File System → MCP Server → Agent

Safety rules:

• Sandbox to specific directories. Never allow ../ traversal.
• Read-only by default. Write requires allowlist.
• Size limits on reads. Don't send 1GB files through MCP.

4. Multi-Step Workflow

Some tools need to orchestrate multiple steps:

server.tool("deploy_service", "Build, test, and deploy a service", {
  service: z.string(),
  environment: z.enum(["staging", "production"]),
}, async ({ service, environment }) => {
  // Step 1: Build
  const buildResult = await build(service);
  if (!buildResult.success) return error(`Build failed: ${buildResult.error}`);

  // Step 2: Test
  const testResult = await runTests(service);
  if (!testResult.success) return error(`Tests failed: ${testResult.summary}`);

  // Step 3: Deploy (only if build + tests pass)
  if (environment === "production") {
    // Extra safety: require confirmation resource
    return {
      content: [{
        type: "text",
        text: `Ready to deploy ${service} to production. Tests: ${testResult.passed}/${testResult.total} passed. Call confirm_deploy to proceed.`
      }]
    };
  }
  const deployResult = await deploy(service, environment);
  return success(`Deployed ${service} to ${environment}: ${deployResult.url}`);
});

5. Aggregator Server

Combine multiple data sources into unified tools:

GitHub + Jira + PagerDuty → DevOps MCP Server → Agent

One get_service_status tool that queries all three and returns a unified view.

---

Phase 7: Security & Hardening

Threat Model

| Threat | Risk | Mitigation | |--------|------|------------| | Prompt injection via tool output | Agent executes malicious instructions in API response | Sanitize output, strip HTML/scripts | | Excessive permissions | Tool has write access it shouldn't | Principle of least privilege per tool | | Data exfiltration | Agent sends sensitive data to wrong tool | Tool allowlists, audit logging | | Denial of service | Agent calls tool in infinite loop | Rate limiting, circuit breakers | | Credential leakage | API keys in tool responses | Strip sensitive fields from output | | SSRF | Agent provides URL that hits internal network | URL allowlisting, no private IPs |

Security Checklist

• [ ] Every tool has minimum required permissions
• [ ] Write operations require explicit confirmation or are behind feature flags
• [ ] API keys/secrets NEVER appear in tool responses
• [ ] Output sanitized (no HTML, no executable content)
• [ ] Rate limits per tool AND per client
• [ ] Audit log: who called what tool, when, with what params
• [ ] Input validation before any external call
• [ ] URL parameters validated against allowlist (prevent SSRF)
• [ ] Timeout on every external call (max 30s default)
• [ ] Circuit breaker: disable tool if error rate > 50% for 5 min

Dangerous Tool Patterns (Avoid)

❌ server.tool("execute_sql", ..., async ({ query }) => db.raw(query))
❌ server.tool("run_command", ..., async ({ cmd }) => exec(cmd))
❌ server.tool("fetch_url", ..., async ({ url }) => fetch(url))  // SSRF
❌ server.tool("write_file", ..., async ({ path, content }) => fs.writeFile(path, content))

Safe Alternatives

✅ Parameterized queries with allowlisted tables
✅ Predefined commands with argument validation
✅ URL allowlist + no private IP ranges
✅ Write to specific directory + filename validation

---

Phase 8: Debugging & Troubleshooting

Common Issues

| Symptom | Likely Cause | Fix | |---------|-------------|-----| | Tool not appearing in agent | Schema error / server not connected | Check mcporter list or client logs | | "Connection refused" | Server not running or wrong port | Verify process, check port | | Tool times out | External API slow or hanging | Add timeout, check API health | | "Invalid params" | Schema mismatch between client/server | Verify schema with --schema flag | | Agent picks wrong tool | Ambiguous descriptions | Rewrite descriptions, add "Use this when..." | | Agent calls tool in loop | Tool returning confusing error | Return clearer error with "do NOT retry" | | Large response crashes | No output truncation | Add pagination or character limit | | Auth errors intermittent | Token expiry | Implement token refresh |

Debug Workflow

1. Verify server starts: node server.js — does it start without errors?
2. List tools: mcporter list my-server --schema — are all tools registered?
3. Call directly: mcporter call my-server.tool_name param=value — does it return expected output?
4. Check client config: Is the server path/URL correct? Are env vars set?
5. Read client logs: Most clients log MCP connection errors
6. Test with Inspector: npx @modelcontextprotocol/inspector for interactive debugging

Logging Template

server.tool("my_tool", description, schema, async (params) => {
  const requestId = crypto.randomUUID().slice(0, 8);
  console.error(`[${requestId}] my_tool called:`, JSON.stringify(params));
  const start = Date.now();
  try {
    const result = await doWork(params);
    console.error(`[${requestId}] my_tool success: ${Date.now() - start}ms`);
    return success(result);
  } catch (error) {
    console.error(`[${requestId}] my_tool error: ${error.message} (${Date.now() - start}ms)`);
    return errorResponse(error.message);
  }
});

Note: Use console.error for logs in stdio transport (stdout is reserved for MCP protocol).

---

Phase 9: MCP Server Selection Guide

Evaluating Existing MCP Servers

Score 0-5 per dimension:

| Dimension | What to Check | |-----------|--------------| | Maintained | Last commit < 3 months? Issues addressed? Version > 1.0? | | Secure | No raw SQL/exec? Auth implemented? Input validated? | | Well-typed | Full JSON Schema for all tools? Descriptions useful? | | Tested | Has tests? CI passing? | | Documented | Setup instructions? Tool descriptions? Examples? | | Lightweight | Minimal dependencies? Fast startup? |

Score < 15/30: Build your own. Score 15-24: Use with caution. Score 25+: Good to use.

Popular MCP Server Categories

| Category | Use Case | Examples | |----------|----------|---------| | Code | GitHub, GitLab, code search | github-mcp, gitlab-mcp | | Data | PostgreSQL, SQLite, Snowflake | postgres-mcp, sqlite-mcp | | Comms | Slack, Discord, email | slack-mcp, gmail-mcp | | Docs | Notion, Confluence, Google Docs | notion-mcp, gdocs-mcp | | DevOps | AWS, GCP, Kubernetes, Terraform | aws-mcp, k8s-mcp | | Search | Brave, Google, vector stores | brave-search, rag-mcp | | Files | Local FS, S3, Google Drive | filesystem-mcp, s3-mcp | | CRM | HubSpot, Salesforce | hubspot-mcp, sfdc-mcp |

---

Phase 10: Architecture Patterns

Single Agent + Multiple Servers

Agent ──┬── github-mcp
        ├── slack-mcp
        ├── postgres-mcp
        └── custom-mcp

Best for: Most use cases. Simple, effective.

Gateway Pattern

Agent ── MCP Gateway ──┬── server-1
                       ├── server-2
                       └── server-3

Gateway handles: auth, rate limiting, logging, routing. Best for: Enterprise, multi-tenant, compliance requirements.

Agent-per-Domain

Orchestrator Agent
├── Code Agent (github-mcp, gitlab-mcp)
├── Data Agent (postgres-mcp, analytics-mcp)
└── Comms Agent (slack-mcp, email-mcp)

Best for: Complex workflows, specialized agents.

Tool Count Guidelines

| Total Tools | Recommendation | |-------------|---------------| | 1-10 | Great. Agent handles well. | | 10-20 | Good. Ensure distinct descriptions. | | 20-30 | Caution. Group by server, review descriptions. | | 30-50 | Risk. Consider agent-per-domain pattern. | | 50+ | Dangerous. Agent WILL pick wrong tools. Split or use gateway. |

---

Phase 11: Publishing MCP Servers

Package Structure

my-mcp-server/
├── src/
│   ├── server.ts        # MCP server entry
│   ├── tools/           # Tool handlers
│   │   ├── search.ts
│   │   └── create.ts
│   ├── auth.ts          # Auth middleware
│   └── config.ts        # Configuration
├── tests/
│   ├── tools.test.ts
│   └── integration.test.ts
├── package.json
├── tsconfig.json
├── README.md            # Setup + tool docs
└── LICENSE

README Template for MCP Servers

# [Service] MCP Server

[One sentence: what this enables]

## Quick Start
[3 steps max to get running]

## Tools
| Tool | Description | Params |
|------|-------------|--------|
[Table of all tools]

## Configuration
[Env vars, auth setup]

## Examples
[2-3 real usage examples with agent conversation]

npm Publishing

# package.json
{
  "name": "@myorg/service-mcp",
  "version": "1.0.0",
  "bin": { "service-mcp": "./dist/server.js" },
  "files": ["dist"],
  "keywords": ["mcp", "model-context-protocol", "ai-tools"]
}

npm publish

---

Quality Rubric (0-100)

| Dimension | Weight | What to Score | |-----------|--------|--------------| | Tool design | 20% | Names, descriptions, granularity, params | | Security | 20% | Auth, input validation, output sanitization, least privilege | | Reliability | 15% | Error handling, timeouts, circuit breakers | | Testing | 15% | Unit + integration coverage, edge cases | | Documentation | 10% | Setup, tool docs, examples | | Performance | 10% | Response time, output size, caching | | Maintainability | 10% | Code structure, types, logging |

Score 0-40: Not production ready. 40-70: Usable with caveats. 70-90: Solid. 90+: Excellent.

---

Common Mistakes

| Mistake | Fix | |---------|-----| | God-tool that does everything | Split into focused tools | | Vague tool descriptions | Write descriptions as if explaining to a new hire | | No error handling | Every external call wrapped in try/catch | | Returning raw API responses | Shape output for agent consumption | | No rate limiting | Add per-tool and per-client limits | | Ignoring output size | Paginate or truncate responses | | Hardcoded credentials | Use env vars or secret manager | | No logging | Can't debug what you can't see | | Testing only happy path | Test errors, timeouts, edge cases | | Building before checking | Search for existing MCP server first |

---

Natural Language Commands

• "Build an MCP server for [service]" → Use Phase 2 templates
• "Add a tool to my MCP server" → Follow tool design rules
• "Secure my MCP server" → Phase 7 checklist
• "Debug MCP connection issue" → Phase 8 workflow
• "Evaluate this MCP server" → Phase 9 scoring
• "Design multi-server architecture" → Phase 10 patterns
• "Publish my MCP server" → Phase 11 structure
• "Convert REST API to MCP" → Phase 6 Pattern 1
• "Add auth to my MCP server" → Phase 3 auth patterns
• "Test my MCP server" → Phase 5 checklist
• "How many tools is too many?" → Phase 10 tool count table
• "Review my tool descriptions" → Phase 2 quality checklist