/mcp-server

name: mcp-server
description: Guide for creating new MCP server integrations

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

| MCP | Capabilities | |-----|--------------| | **user-notion** | Page/block CRUD, search, comments | | **cursor-ide-browser** | Navigation, clicks, screenshots, console | | **user-n8n-mcp** | Workflow search, details, execution | | **user-context7** | Library docs lookup | | **figma** | Design specs, code generation from frames |

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