MCP Configuration

Overview

Once you’ve generated an API key, you can configure MCP-compatible clients to connect to PromptRepo. This page covers setup for:

Claude Desktop (Anthropic’s native app)
Claude Code (VS Code extension and web editor)
Generic MCP clients (cURL, Postman, custom scripts)

All configurations require your deployed PromptRepo URL (e.g., https://your-app.vercel.app) and a valid API key.

Claude Desktop Configuration

Claude Desktop reads MCP server configurations from a JSON file in your home directory.

Locate Config File

The config file location depends on your operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist, create it with an empty { "mcpServers": {} } object.

Add PromptRepo Server

Edit the file to include your PromptRepo MCP server:

claude_desktop_config.json

{
  "mcpServers": {
    "promptrepo": {
      "url": "https://your-app.vercel.app/api/mcp",
      "headers": {
        "x-api-key": "pr_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
      }
    }
  }
}

Replace:

your-app.vercel.app → Your actual deployment URL
pr_live_abc123... → Your API key from /profile

Restart Claude Desktop

Close and reopen Claude Desktop for changes to take effect.

Verify Connection

In a new conversation, type:

“Search my PromptRepo for React hooks”

Claude should call the search_prompts tool and return results.

Security: The claude_desktop_config.json file contains your plaintext API key. Ensure it’s readable only by your user account:

chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Claude Code Configuration

Claude Code (the VS Code extension and web editor) uses the same configuration format.

VS Code Extension

Open Settings

Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) and search for “Claude Code: Edit MCP Settings”.

Add Server Config

Add your PromptRepo server to the mcpServers object:

{
  "mcpServers": {
    "promptrepo": {
      "url": "https://your-app.vercel.app/api/mcp",
      "headers": {
        "x-api-key": "pr_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
      }
    }
  }
}

Reload Window

Press Cmd+Shift+P → “Developer: Reload Window” to apply changes.

Web Editor (claude.ai/code)

Open Project Settings

Click the gear icon in the top-right corner of the editor.

Navigate to MCP Servers

Select the “MCP Servers” tab.

Add Server

Click “Add Server” and fill in:

Name: promptrepo
URL: https://your-app.vercel.app/api/mcp
Headers:
```
{ "x-api-key": "pr_live_abc123..." }
```

Save and Test

Click “Save”. In the chat, ask Claude to list your prompts:

“List my prompts from PromptRepo”

Multiple Servers (Advanced)

You can connect multiple PromptRepo instances (e.g., production and staging) or other MCP servers:

claude_desktop_config.json

{
  "mcpServers": {
    "promptrepo-prod": {
      "url": "https://app.promptrepo.com/api/mcp",
      "headers": {
        "x-api-key": "pr_live_production_key"
      }
    },
    "promptrepo-staging": {
      "url": "https://staging.promptrepo.com/api/mcp",
      "headers": {
        "x-api-key": "pr_live_staging_key"
      }
    },
    "other-mcp-server": {
      "url": "https://example.com/mcp",
      "headers": {
        "authorization": "Bearer other_api_key"
      }
    }
  }
}

Claude will automatically detect and use all configured servers. Prefix your requests with the server name to disambiguate:

“Search promptrepo-prod for authentication flows”

Environment Variable Substitution

Some MCP clients support environment variable expansion in config files:

claude_desktop_config.json

{
  "mcpServers": {
    "promptrepo": {
      "url": "${PROMPTREPO_URL}/api/mcp",
      "headers": {
        "x-api-key": "${PROMPTREPO_API_KEY}"
      }
    }
  }
}

Then set environment variables before launching Claude:

export PROMPTREPO_URL=https://your-app.vercel.app
export PROMPTREPO_API_KEY=pr_live_abc123...
open -a "Claude"  # macOS

Compatibility: Environment variable substitution is not supported in all MCP clients. Test thoroughly or use hardcoded values.

Testing with cURL

You can test your MCP server without an AI client using cURL:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: pr_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_prompts",
      "arguments": { "limit": 5 }
    }
  }'

Expected Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"prompts\": [\n    {\n      \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"title\": \"React Hook Template\",\n      \"description\": \"Generate custom React hooks\",\n      \"variables\": [\"hookName\", \"stateType\"]\n    }\n  ]\n}"
      }
    ],
    "isError": false
  }
}

Troubleshooting

Error: Invalid API key

Cause: The API key is incorrect, revoked, or improperly formatted.Solution:

Verify the key in /profile (check last 8 characters)
Ensure no extra spaces or line breaks in the config file
Generate a new key and update the config

Error: Method not found

Cause: The method field in the JSON-RPC request doesn’t match a supported tool.Solution:

Use "method": "tools/call" for all tool invocations
Pass the actual tool name in params.name (e.g., "list_prompts")
Supported tools: list_prompts, get_prompt, resolve_prompt, search_prompts

Claude doesn't call MCP tools

Cause: The MCP server isn’t registered or Claude doesn’t recognize the request.Solution:

Restart Claude Desktop/VS Code after editing config
Use explicit phrasing: “Search my PromptRepo for…”
Check Claude’s developer console for connection errors

CORS errors in browser-based clients

Cause: PromptRepo’s MCP endpoint has CORS enabled, but your deployment might have middleware blocking it.Solution:

Verify Access-Control-Allow-Origin: * in response headers
Check that /api/mcp is excluded from auth middleware (see src/middleware.ts)

Connection timeout

Cause: Your deployment URL is incorrect or the server is down.Solution:

Test the endpoint with cURL (see examples above)
Verify the URL has no typos or trailing slashes
Check deployment status in Vercel/Railway dashboard

Production Environment Variables

Do not skip this step when deploying to production!

The MCP endpoint requires the SUPABASE_SERVICE_ROLE_KEY environment variable to bypass RLS and authenticate users via API keys.

Get Service Role Key

In your Supabase dashboard:

Go to Settings → API
Copy the service_role key (not the anon key)

Add to Deployment

In Vercel/Railway/Render:

Navigate to your project settings
Add environment variable:
- Name: SUPABASE_SERVICE_ROLE_KEY
- Value: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (your service role key)

Redeploy

Trigger a redeployment to apply the environment variable.

Without this key, the MCP endpoint will return INTERNAL_ERROR for all authenticated requests.

Implementation Reference

The MCP route handler is implemented in src/app/api/mcp/route.ts:

src/app/api/mcp/route.ts

export async function POST(request: Request): Promise<Response> {
  // Step 1: Resolve caller identity from API key headers
  let userId: string | null = null;

  const authHeader = request.headers.get('Authorization');
  const xApiKeyHeader = request.headers.get('x-api-key');

  // Prefer `Authorization: Bearer <key>` over `x-api-key`.
  const rawKey =
    authHeader?.startsWith('Bearer ')
      ? authHeader.slice('Bearer '.length).trim()
      : (xApiKeyHeader?.trim() ?? null);

  if (rawKey) {
    const result = await verifyApiKey(rawKey);
    if (!result.valid) {
      return rpcError(null, MCP_ERROR_CODES.INVALID_API_KEY, 'Invalid API key.');
    }
    userId = result.userId;
  }
  // If no key header is present, userId stays null → anonymous access

  // Step 2-5: Parse, validate, dispatch, return response
  // ...
}

See the full source at src/app/api/mcp/route.ts:71-138.

Next Steps

Overview

Learn about MCP protocol and available tools

API Reference

Detailed JSON-RPC schemas and error codes

Setup

Available Tools

AI Agent Integration

Overview

Claude Desktop Configuration

Claude Code Configuration

VS Code Extension

Web Editor (claude.ai/code)

Multiple Servers (Advanced)

Environment Variable Substitution

Testing with cURL

Expected Response Format

Troubleshooting

Production Environment Variables

Implementation Reference

Next Steps

Overview

API Reference

Build docs developers (and LLMs) love

Setup

Available Tools

AI Agent Integration

​Overview

​Claude Desktop Configuration

​Claude Code Configuration

​VS Code Extension

​Web Editor (claude.ai/code)

​Multiple Servers (Advanced)

​Environment Variable Substitution

​Testing with cURL

​Expected Response Format

​Troubleshooting

​Production Environment Variables

​Implementation Reference

​Next Steps

Overview

API Reference

Build docs developers (and LLMs) love

Overview

Claude Desktop Configuration

Claude Code Configuration

VS Code Extension

Web Editor (claude.ai/code)

Multiple Servers (Advanced)

Environment Variable Substitution

Testing with cURL

Expected Response Format

Troubleshooting

Production Environment Variables

Implementation Reference

Next Steps