platform-2step-mcp 0.8.1

MCP server for Platform-2Step API with human-in-the-loop confirmation

Platform-2Step MCP

MCP server that enables AI agents (Claude, GPT, etc.) to interact with AgendaPro's Platform API safely through a human-in-the-loop confirmation system.

All mutations require human confirmation — the AI agent can only create pending operations, never execute them directly.

Prerequisites

• Python 3.11+ — check with python3 --version
• uv (recommended) — Python package manager

Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

After installing, restart your terminal or run source ~/.bashrc (or ~/.zshrc).

Installation

Option A: Claude Code (recommended)

Add to your project's .claude/mcp.json (or ~/.claude/mcp.json for global):

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Option B: Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Option C: Cursor

In Cursor, go to Settings > MCP and add a new server with this configuration:

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Alternatively, create a .cursor/mcp.json file in your project root with the same content.

Note: uvx downloads and runs the package from PyPI automatically — no manual install needed.

Authentication

Before using the MCP, you must authenticate once. The MCP uses OAuth 2.0 Device Flow — you'll be shown a URL and a code to enter in your browser.

# Set the BFF URL
export PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff

# Authenticate (opens browser)
uvx platform-mcp-auth login

You'll see something like:

Connecting to https://ap-api.agendapro.com/platform-2steps-bff...


============================================================
Authentication required!
============================================================

1. Open your browser to:
   https://mcp.agendapro.com/v1/auth/login...

2. After authenticating, copy the completion code from
   the browser and paste it below.

This code expires in 10 minutes.
============================================================

Enter completion code (or @filepath to read from file):


============================================================
Authentication successful!
============================================================
Token expires in: 1h 0m

Tokens are cached at ~/.platform-mcp/tokens.json and reused automatically.

Auth CLI commands

Command	Description
uvx platform-mcp-auth login	Authenticate (interactive)
uvx platform-mcp-auth login --force	Re-authenticate even if tokens are valid
uvx platform-mcp-auth status	Check if tokens are valid
uvx platform-mcp-auth logout	Clear cached tokens

Important: Always set PLATFORM_2STEPS_BFF_URL before running auth commands.

Using Multiple Environments

To use both staging and production simultaneously, configure separate token paths:

{
  "mcpServers": {
    "platform-2step-staging": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendaprodev.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendaprodev.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-staging.json"
      }
    },
    "platform-2step-prod": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-prod.json"
      }
    }
  }
}

Authenticate each environment separately:

# Staging
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendaprodev.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-staging.json \
uvx platform-mcp-auth login

# Production
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-prod.json \
uvx platform-mcp-auth login

Available Tools

Once connected, the MCP provides these tools to the AI agent:

Read (no confirmation needed)

• Categories: list_categories, get_category
• Services: list_services, list_services_by_category, get_service
• Bookings: list_bookings, get_booking
• Locations: list_locations, get_location
• Providers: list_providers, get_provider
• Memberships: list_memberships, get_membership
• Users: get_user

Mutations (require human confirmation)

• Batch operations: create_batch — creates up to 50 operations (create, update, delete) that must be confirmed by the user in the AgendaPro frontend

Analytics (read-only SQL)

• query_analytics_db — execute SQL against synced analytics data
• get_analytics_status — check data sync status
• refresh_analytics_data — trigger data refresh

Troubleshooting

"Not authenticated" error

Error: Not authenticated. Run 'platform-mcp-auth login' first.

Your tokens expired or were never created. Run uvx platform-mcp-auth login.

"Configuration error: PLATFORM_2STEPS_BFF_URL is required"

The environment variable is not set. Make sure it's in your mcp.json config under env.

MCP tools not showing in Claude

1. Check the MCP server is running: look for errors in Claude Code's MCP logs
2. Verify auth: uvx platform-mcp-auth status
3. Restart Claude Code / Claude Desktop after config changes

"uvx: command not found"

Install uv first (see Prerequisites).

Environment Variables

Variable	Required	Default	Description
PLATFORM_2STEPS_BFF_URL	Yes	—	BFF URL for API integration (staging or production)
API_HOST_PUBLIC	No	Falls back to PLATFORM_2STEPS_BFF_URL	Public hostname for browser-facing URLs (e.g., mcp.agendapro.com)
PLATFORM_MCP_TOKEN_PATH	No	~/.platform-mcp/tokens.json	Token storage location
LOG_LEVEL	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
DEBUG_HTTP	No	false	Enable cURL-style HTTP request/response logging

Documentation

For comprehensive documentation including architecture, security, and development guides, see CLAUDE.md.

License

MIT