wiki/public/raw/how-to-use-mcp-server.md

How to Use the MCP Server with MarkDown Sync

Guide to using the HTTP-based Model Context Protocol(MCP) server at www.markdown.fast/mcp with Cursor and other AI tools

---

Type: post Date: 2025-12-28 Reading time: 5 min read Tags: mcp, cursor, ai, tutorial, netlify

This site includes an HTTP-based Model Context Protocol (MCP) server that allows AI tools like Cursor, Claude Desktop, and other MCP-compatible clients to access blog content programmatically.

What is MCP?

The Model Context Protocol is an open standard for connecting AI applications to external data sources. It enables AI assistants to read content, search, and retrieve information from connected systems.

Our MCP server exposes read-only tools for accessing:

• Blog posts (list, get by slug, search)
• Static pages (list, get by slug)
• Homepage data (featured content, recent posts)
• Full content export

Endpoint URL

The MCP server is available 24/7 at:

https://www.markdown.fast/mcp

No authentication is required for public access.

Available tools

The server exposes seven tools:

Tool	Description
list_posts	Get all published blog posts with metadata
get_post	Get a single post by slug with full content
list_pages	Get all published pages
get_page	Get a single page by slug with full content
get_homepage	Get homepage data with featured and recent posts
search_content	Full text search across posts and pages
export_all	Batch export all content

Client configuration

Cursor

Add to your Cursor MCP configuration file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "markdown-fast": {
      "url": "https://www.markdown.fast/mcp"
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "markdown-fast": {
      "url": "https://www.markdown.fast/mcp"
    }
  }
}

With API key (optional)

If you have an API key for higher rate limits:

{
  "mcpServers": {
    "markdown-fast": {
      "url": "https://www.markdown.fast/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Rate limiting

The server uses Netlify's built-in rate limiting:

• Public access: 50 requests per minute per IP address
• Authenticated access: Higher limits with API key

When rate limited, the server returns HTTP 429. Wait a minute before retrying.

Example requests

Initialize connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

List available tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Get all posts

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_posts",
    "arguments": {}
  }
}

Get a specific post

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_post",
    "arguments": {
      "slug": "setup-guide"
    }
  }
}

Search content

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "search_content",
    "arguments": {
      "query": "markdown"
    }
  }
}

Testing with curl

Test the server directly:

# Initialize
curl -X POST https://www.markdown.fast/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# List tools
curl -X POST https://www.markdown.fast/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Get all posts
curl -X POST https://www.markdown.fast/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_posts","arguments":{}}}'

Security

The MCP server is designed with security in mind:

• Read-only access: No mutations or writes are exposed
• Public content: Uses the same queries as the public website
• Rate limiting: Prevents abuse via Netlify's built-in rate limiting
• HTTPS encryption: All traffic is encrypted
• Optional authentication: API keys available for higher limits

For your own fork

When you fork this site, the MCP server is already included and will automatically connect to your Convex deployment. Here's how to set it up:

Prerequisites

1. Fork the repository to your GitHub account
2. Set up Convex backend (see Setup Guide)
3. Deploy to Netlify (see Setup Guide)

Setup Steps

1. Set Convex URL in Netlify

   The MCP server needs your Convex deployment URL to fetch content. Add this environment variable in your Netlify dashboard:

   • Go to Site Settings > Environment Variables
   • Add VITE_CONVEX_URL with your production Convex URL (e.g., https://your-deployment.convex.cloud)

2. Deploy your site

   The MCP server is already configured in netlify/edge-functions/mcp.ts and netlify.toml. When you deploy to Netlify, the server will be available at:

   https://your-site.netlify.app/mcp
   

   Or your custom domain:

   https://yourdomain.com/mcp
   

3. Optional: Set API key for higher rate limits

   If you want authenticated access with higher rate limits:

   • Add MCP_API_KEY to your Netlify environment variables
   • Use this key in your client configuration (see "With API key" section above)

How it works

The MCP server reads from your Convex database using the same queries as your public website. Any content you sync with npm run sync or npm run sync:prod will be immediately available via the MCP server.

Testing your fork's MCP server

After deploying, test your MCP server:

# Replace with your site URL
curl -X POST https://your-site.netlify.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should receive a response listing all seven available tools.

Client configuration for your fork

Update your Cursor or Claude Desktop configuration to use your fork's endpoint:

{
  "mcpServers": {
    "my-blog": {
      "url": "https://your-site.netlify.app/mcp"
    }
  }
}

Files included

The MCP server implementation is included in your fork:

• netlify/edge-functions/mcp.ts - MCP server implementation
• netlify.toml - Edge function route configuration
• package.json - Includes @modelcontextprotocol/sdk dependency

No additional code changes needed. Just set the environment variable and deploy.

Troubleshooting

Server returns 500 error

Check that VITE_CONVEX_URL is set in your Netlify environment variables.

Rate limit exceeded

Wait 60 seconds before retrying. Consider using an API key for higher limits.

Tool not found

Verify the tool name matches one of the seven available tools exactly.

Invalid JSON-RPC

Ensure your request includes:

• "jsonrpc": "2.0"
• A numeric or string id
• A method string

Resources

• Model Context Protocol specification
• Cursor MCP documentation
• Claude Desktop MCP setup