How to Connect Cursor to Custom MCP Servers: Step-by-Step Guide

sequenceDiagram
    autonumber
    actor Dev as Software Engineer
    participant Cursor as Cursor IDE (MCP Client)
    participant Config as .cursor/mcp.json
    participant Stdio as OS stdio Pipe (stdin/stdout)
    participant Server as Custom MCP Server
    participant DB as SQLite / Postgres Database

    Dev->>Config: Define mcpServers JSON configuration
    Cursor->>Config: Read .cursor/mcp.json on project load
    Cursor->>Stdio: Spawn child process (e.g. node server.js)
    Cursor->>Server: Send JSON-RPC initialize request
    Server-->>Cursor: Return list of available Tools, Resources & Prompts
    Dev->>Cursor: Prompt: "Query user table schema and record count"
    Cursor->>Server: Send tools/call request (name: "query_db")
    Server->>DB: Execute SQL SELECT query
    DB-->>Server: Return query record set
    Server-->>Cursor: Send JSON-RPC tools/call response (content payload)
    Cursor-->>Dev: Synthesize answer with live database context

# Project-level (recommended first):
mkdir -p .cursor && touch .cursor/mcp.json

# Global (macOS/Linux):
mkdir -p ~/.cursor && touch ~/.cursor/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${env:DATABASE_URL}"
      ],
      "envFile": "${workspaceFolder}/.env"
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

mkdir my-custom-mcp-server && cd my-custom-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

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

const SystemStatusInputSchema = z.object({
  serviceName: z.string().describe("Name of the microservice to inspect"),
});

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_service_status",
        description: "Returns operational health and latency metrics for a named internal microservice",
        inputSchema: {
          type: "object",
          properties: {
            serviceName: {
              type: "string",
              description: "Name of the microservice (e.g. auth-service, billing-api)",
            },
          },
          required: ["serviceName"],
        },
      },
    ],
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_service_status") {
    const { serviceName } = SystemStatusInputSchema.parse(request.params.arguments);
    
    const statusData = {
      service: serviceName,
      status: "healthy",
      latencyMs: 42,
      uptimePercentage: 99.98,
      timestamp: new Date().toISOString(),
    };

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(statusData, null, 2),
        },
      ],
    };
  }

  throw new Error(`Tool not found: ${request.params.name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // Never use console.log() — stdout is reserved for JSON-RPC!
  console.error("Custom MCP Server listening over stdio...");
}

main().catch((err) => {
  console.error("Fatal server error:", err);
  process.exit(1);
});

{
  "mcpServers": {
    "my-custom-tool": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "${workspaceFolder}/my-custom-mcp-server/server.ts"]
    }
  }
}