# 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

```bash
# 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):

```json
{
  "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):

```json
{
  "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:

```json
{
  "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.

```bash
# 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...

Visit: https://agendapro-staging.auth.us-west-2.amazoncognito.com/...
Enter code: ABCD-1234

Waiting for authorization...

============================================================
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:

```json
{
  "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:

```bash
# 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](#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](./CLAUDE.md)**.

## License

MIT
