Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
API Coverage vs. Workflow Tools:
Balance comprehensive API endpoint coverage with specialized workflow tools. When uncertain, prioritize comprehensive API coverage.
Tool Naming and Discoverability:
Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.
Context Management:
Design tools that return focused, relevant data. Agents benefit from concise tool descriptions and the ability to filter/paginate results.
Actionable Error Messages:
Error messages should guide agents toward solutions with specific suggestions and next steps.
1.2 Study MCP Protocol Documentation
Start with the sitemap: https://modelcontextprotocol.io/sitemap.xml
Key pages to review:
Specification overview and architecture
Transport mechanisms (streamable HTTP, stdio)
Tool, resource, and prompt definitions
1.3 Select Language and Transport
Language Selection:
Language
Best For
SDK
TypeScript (recommended)
General MCP servers, broad compatibility
@modelcontextprotocol/sdk
Python
Data/ML pipelines, FastAPI integration
mcp (FastMCP)
C#/.NET
Azure/Microsoft ecosystem, enterprise
Microsoft.Mcp.Core
Transport Selection:
Transport
Use Case
Characteristics
Streamable HTTP
Remote servers, multi-tenant, Agent Service
Stateless, scalable, requires auth
stdio
Local servers, desktop apps
Simple, single-user, no network
Phase 2: Implementation
TypeScript Server (Recommended)
import { McpServer } from"@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from"@modelcontextprotocol/sdk/server/stdio.js";
import { z } from"zod";
const server = newMcpServer({
name: "my-mcp-server",
version: "1.0.0",
});
// Register a tool with Zod schema
server.tool(
"get_weather",
"Get current weather for a city",
{ city: z.string().describe("City name") },
async ({ city }) => ({
content: [{ type: "text", text: JSON.stringify({ city, temp: "72°F" }) }],
})
);
// Start serverconst transport = newStdioServerTransport();
await server.connect(transport);
Python Server (FastMCP)
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
mcp = FastMCP("my-mcp-server")
classWeatherParams(BaseModel):
city: str = Field(description="City name")
@mcp.tool(description="Get current weather for a city")asyncdefget_weather(params: WeatherParams) -> dict:
return {"city": params.city, "temp": "72°F"}
if __name__ == "__main__":
mcp.run()
C#/.NET Server
using Microsoft.Mcp.Core;
var server = new McpServerBuilder()
.WithName("my-mcp-server")
.WithVersion("1.0.0")
.AddTool("get_weather", "Get current weather", async (string city) =>
new { city, temp = "72°F" })
.Build();
await server.RunAsync();
Tool Design Best Practices
Input Schema
Use Zod (TypeScript) or Pydantic (Python) for validation
Include constraints and clear descriptions
Add examples in field descriptions
Output Schema
Define outputSchema where possible for structured data
Use structuredContent in tool responses (TypeScript SDK feature)
Answer Verification: Solve each question yourself to verify answers
Evaluation Requirements
Each question must be:
Independent: Not dependent on other questions
Read-only: Only non-destructive operations required
Complex: Requiring multiple tool calls and deep exploration
Realistic: Based on real use cases humans would care about
Verifiable: Single, clear answer that can be verified by string comparison
Stable: Answer won't change over time
Output Format
<evaluation><qa_pair><question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined?</question><answer>3</answer></qa_pair><!-- More qa_pairs... --></evaluation>
Common Issues
Issue
Cause
Solution
Tools not appearing
Server not responding to tools/list
Verify tool registration, check server startup
Stdout pollution
Debug output on stdout
Move debug output to stderr
Connection refused
Port conflict or server crash
Check port availability, review logs
Timeout
Slow API calls
Add timeout handling, implement pagination
Schema validation
Invalid input schema
Use Zod/Pydantic with proper constraints
Synapse Connection
This skill complements:
mcp-development — Core MCP protocol patterns and architecture
azure-architecture-patterns — When building Azure-integrated MCP servers
testing-strategies — For comprehensive MCP server testing
