code-society-25-2

MCP Server Setup for fullstack_demo

This document explains how to use the Model Context Protocol (MCP) server that has been integrated into the fullstack_demo application. This allows AI agents like Claude Desktop to securely interact with your todos through a standardized protocol.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI assistants to securely connect to external tools and services. This implementation allows Claude Desktop and other MCP-compatible AI agents to:

All operations are authenticated using Clerk OAuth tokens, ensuring secure access to your data.

Architecture

The MCP server is built using:

Key Components

  1. MCP Route Handler (src/app/[transport]/route.ts)
    • Defines MCP tools for todo operations
    • Supports both /mcp (HTTP) and /sse (Server-Sent Events) transports
    • Authenticates requests using Clerk OAuth tokens
  2. OAuth Metadata Endpoints
    • /.well-known/oauth-protected-resource/mcp - Resource metadata
    • /.well-known/oauth-authorization-server - Authorization server metadata (backward compatibility)
  3. Middleware (src/middleware.ts)
    • Updated to allow public access to .well-known endpoints
    • Maintains authentication for all other routes

Setup Instructions

1. Enable Dynamic Client Registration in Clerk

IMPORTANT: Before the MCP server can work, you must enable dynamic client registration in your Clerk Dashboard.

  1. Go to the Clerk Dashboard
  2. Navigate to Configure → OAuth Applications
  3. Toggle on Dynamic client registration

This allows MCP-compatible clients to automatically register themselves during the OAuth flow.

2. Start the Development Server

cd /Users/anthonymays/source/forks/code-society-25-2/lib/javascript/fullstack_demo
npm run dev

The server will start on http://localhost:3000 (or your configured port).

3. Connect AI Agents to Your MCP Server

The easiest way to connect AI agents to your MCP server is using the mcp-remote utility:

npx -y mcp-remote http://localhost:3000/mcp

This command:

Alternative Method: Manual Configuration

If you prefer to manually configure your AI agent:

  1. Locate your Claude Desktop configuration file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add your MCP server configuration:
{
  "mcpServers": {
    "fullstack_demo_todos": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "authorizationUrl": "http://localhost:3000/.well-known/oauth-authorization-server"
      }
    }
  }
}

Note: The tokenUrl is automatically discovered from the authorization server metadata.

  1. Restart your AI agent

  2. When the agent tries to use the MCP server, you’ll be prompted to authenticate via Clerk OAuth.

4. Production Deployment

When deploying to production:

  1. Connect to your production MCP server using mcp-remote: 
    npx -y mcp-remote https://your-production-domain.com/mcp

    Or update your AI agent’s configuration manually:

    {
  "mcpServers": {
    "fullstack_demo_todos": {
      "url": "https://your-production-domain.com/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "authorizationUrl": "https://your-production-domain.com/.well-known/oauth-authorization-server"
      }
    }
  }
}
  2. Ensure your production environment has all required environment variables set:
    • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
    • CLERK_SECRET_KEY
    • Database connection strings
    • Any other app-specific variables

Available MCP Tools

1. get-todos

Gets all todos for the authenticated user.

Parameters: None

Example Response:

[
  {
    "id": 1,
    "text": "Buy groceries",
    "completed": false
  },
  {
    "id": 2,
    "text": "Finish homework",
    "completed": true
  }
]

2. create-todo

Creates a new todo for the authenticated user.

Parameters:

Example Response:

{
  "id": 1234567890,
  "text": "New todo item",
  "completed": false
}

3. update-todo

Updates an existing todo for the authenticated user.

Parameters:

Example Response:

{
  "id": 1234567890,
  "text": "Updated todo text",
  "completed": true
}

4. delete-todo

Deletes a todo for the authenticated user.

Parameters:

Example Response:

{
  "success": true,
  "deletedId": 1234567890
}

5. get-clerk-user-data

Gets data about the Clerk user that authorized the request.

Parameters: None

Example Response:

{
  "id": "user_xxxxxxxxxxxxx",
  "firstName": "John",
  "lastName": "Doe",
  "emailAddresses": [...],
  ...
}

Using the MCP Server with Claude

Once configured, you can interact with your todos naturally through Claude:

Example Prompts:

Claude will use the appropriate MCP tools to interact with your todo list securely.

Security

Troubleshooting

MCP Server Not Connecting

  1. Verify the development server is running
  2. Check that dynamic client registration is enabled in Clerk Dashboard
  3. Ensure the URLs in Claude Desktop config match your server URLs
  4. Check browser/Claude console for error messages

Authentication Errors

  1. Verify your Clerk API keys are set correctly in .env
  2. Ensure the Clerk Frontend API URL in Claude config is correct
  3. Try re-authenticating by disconnecting and reconnecting the MCP server in Claude

Tool Execution Errors

  1. Check the Next.js server logs for detailed error messages
  2. Verify the database is accessible and properly configured
  3. Ensure the authenticated user has permission to perform the action

Files Created/Modified

New Files

Modified Files

Dependencies Added

Additional Resources

This site is open source. Improve this page.