Some links in this article are affiliate links. We earn a commission at no extra cost to you when you purchase through them. Full disclosure.

Quick reference for MCP (Model Context Protocol) — the standard for connecting AI tools to external data and services.

What MCP does

AI Tool (Claude Code, Cursor, Gemini CLI)
    │
    │ MCP Protocol
    ▼
MCP Server (your code)
    │
    ▼
Your data (database, API, filesystem, etc.)

MCP lets AI tools use your custom tools without provider-specific integrations.

Create a server (TypeScript)

npm init -y
npm install @modelcontextprotocol/sdk

// server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-tools", version: "1.0.0" }, {
  capabilities: { tools: {} },
});

// Define a tool
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "search_docs",
    description: "Search project documentation",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
  }],
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "search_docs") {
    const results = await searchDocs(request.params.arguments.query);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
});

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

Full tutorial: Build an MCP Server in TypeScript

Create a server (Python)

pip install mcp

# server.py
from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("my-tools")

@server.list_tools()
async def list_tools():
    return [Tool(
        name="run_query",
        description="Run a SQL query",
        inputSchema={
            "type": "object",
            "properties": {"sql": {"type": "string"}},
            "required": ["sql"],
        },
    )]

@server.call_tool()
async def call_tool(name, arguments):
    if name == "run_query":
        result = await db.execute(arguments["sql"])
        return [TextContent(type="text", text=str(result))]

if __name__ == "__main__":
    import asyncio
    from mcp.server.stdio import stdio_server
    asyncio.run(stdio_server(server))

Full tutorial: Build an MCP Server in Python

Connect to Claude Code

// .claude/mcp.json in your project root
{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["tsx", "server.ts"]
    },
    "database": {
      "command": "python",
      "args": ["db_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Full setup: MCP + Claude Code Setup

Connect to Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["tsx", "server.ts"]
    }
  }
}

Full setup: MCP + Cursor Setup

Connect to Gemini CLI

gemini extensions install ./path-to-server
# Or via npm package
gemini extensions install @your-org/mcp-server

Tool definition schema

{
  name: "tool_name",           // Unique identifier
  description: "What it does", // AI reads this to decide when to use it
  inputSchema: {               // JSON Schema for arguments
    type: "object",
    properties: {
      arg1: { type: "string", description: "What this arg is" },
      arg2: { type: "number", description: "Optional number" },
    },
    required: ["arg1"],        // Which args are required
  },
}

Tip: Write clear descriptions. The AI uses them to decide when and how to call your tool.

Resource definitions

// Expose data the AI can read
server.setRequestHandler("resources/list", async () => ({
  resources: [{
    uri: "docs://api-reference",
    name: "API Reference",
    mimeType: "text/markdown",
  }],
}));

server.setRequestHandler("resources/read", async (request) => ({
  contents: [{
    uri: request.params.uri,
    text: await readFile("./docs/api.md", "utf-8"),
  }],
}));

Debugging

# Test your server directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node server.js

# Use MCP Inspector
npx @modelcontextprotocol/inspector node server.js

# Check Claude Code logs
# Look for MCP connection errors in the terminal output

Full debugging guide: MCP Debugging Guide

Security checklist

• Validate all tool inputs before execution
• Don’t expose write access unless necessary
• Sanitize SQL queries (use parameterized queries)
• Restrict file access to project directory
• Log all tool calls for audit
• Don’t hardcode secrets in server code

Full checklist: MCP Security Checklist

Popular MCP servers

Server	What it does
Filesystem	Read/write local files
PostgreSQL	Query databases
Slack	Send/read messages
GitHub	Manage repos, PRs, issues
Playwright	Browser automation
Context7	Documentation lookup

Full list: Best MCP Servers

Speed up your workflow — Raycast lets you manage MCP servers from a keyboard shortcut.

Related: What is MCP? · MCP Complete Developer Guide · Build MCP Server TypeScript · Build MCP Server Python · MCP Security Checklist · Best MCP Servers · MCP vs Function Calling