MCP Server Creation Guide

Use this skill when creating a new MCP server integration.

MCP Folder Structure

MCPs live in: ~/.cursor/projects/<project>/mcps/<server-name>/

mcps/
├── user-notion/
│   └── tools/
│       ├── API-retrieve-a-page.json
│       └── ...
├── cursor-ide-browser/
│   └── tools/
│       ├── browser_navigate.json
│       └── ...
└── user-n8n-mcp/
    └── tools/
        └── ...

Tool Descriptor Format

Each tool is a JSON file:

{
  "name": "tool-name",
  "description": "What this tool does",
  "arguments": {
    "type": "object",
    "properties": {
      "param1": { "type": "string", "description": "..." }
    },
    "required": ["param1"]
  }
}

Usage Pattern

1. Read tool descriptor before calling
2. Use CallMcpTool with server, toolName, arguments
3. Handle response appropriately

Example Call

CallMcpTool:
  server: "user-notion"
  toolName: "API-retrieve-a-page"
  arguments: { "page_id": "abc123" }

Existing MCPs Reference

Creating a New MCP

1. Create folder: mcps/<server-name>/tools/
2. Add tool descriptors as JSON files
3. Configure server in ~/.cursor/mcp.json
4. Restart Cursor (Cmd+Shift+P > "Reload Window")
5. Test with CallMcpTool

Authentication Patterns

Pattern 1: API Token (env block)

For MCPs that use API keys (Notion, n8n):

"mcp-name": {
  "command": "npx",
  "args": ["-y", "@package/mcp-server"],
  "env": {
    "API_KEY": "your-token-here"
  }
}

Pattern 2: URL-based (no auth)

For MCPs that connect to local servers (Figma desktop):

"mcp-name": {
  "url": "http://127.0.0.1:PORT/mcp"
}

Pattern 3: OAuth (remote URL)

For MCPs that use browser OAuth (Figma remote):

"mcp-name": {
  "url": "https://service.com/mcp"
}

After adding, click "Connect" in Cursor MCP settings to authorize.

Troubleshooting

Installation loops infinitely:
- Cancel and manually edit ~/.cursor/mcp.json
- Add config block directly, then restart Cursor

MCP not appearing:
- Check JSON syntax is valid
- Verify package name is correct
- Restart Cursor after changes

Best Practices

• Always read tool schema before calling
• Handle errors gracefully
• Use descriptive tool names
• Document required vs optional parameters