# Prompt Forge MCP Server

Python MCP server that exposes [Prompt Forge](https://secureprompt.tech) secure gateway tools over the [Model Context Protocol](https://modelcontextprotocol.io/).

Works with any MCP-compatible AI CLI: **Claude Code**, **Claude Desktop**, **Gemini CLI**, **OpenAI Codex CLI**, or any custom MCP client.

## Install

```bash
pip install promptforge-mcp
```

## Quick Start

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "promptforge": {
      "command": "promptforge-mcp",
      "env": {
        "PROMPTFORGE_API_KEY": "your-api-key",
        "PROMPTFORGE_ORG_ID": "your-org-id",
        "PROMPTFORGE_ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add promptforge -- promptforge-mcp
```

Then export the required environment variables in your shell before launching Claude Code.

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "promptforge": {
      "command": "promptforge-mcp",
      "args": [],
      "env": {
        "PROMPTFORGE_API_KEY": "your-api-key",
        "PROMPTFORGE_ORG_ID": "your-org-id",
        "PROMPTFORGE_ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}
```

### OpenAI Codex CLI

Add to `~/.codex/config.json`:

```json
{
  "mcpServers": {
    "promptforge": {
      "command": "promptforge-mcp",
      "args": [],
      "env": {
        "PROMPTFORGE_API_KEY": "your-api-key",
        "PROMPTFORGE_ORG_ID": "your-org-id",
        "PROMPTFORGE_ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}
```

### Run directly (stdio)

Any MCP client that launches a subprocess can use this directly:

```bash
export PROMPTFORGE_API_KEY="your-api-key"
export PROMPTFORGE_ORG_ID="your-org-id"
export PROMPTFORGE_ADMIN_TOKEN="your-admin-token"
promptforge-mcp
```

### Run as HTTP/SSE server

For clients that connect over HTTP instead of spawning a subprocess:

```bash
promptforge-mcp --http
# or
MCP_TRANSPORT=http MCP_PORT=8765 promptforge-mcp
```

Then point your MCP client at `http://localhost:8765/sse`.

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `PROMPTFORGE_API_KEY` | Yes (for gateway) | — | API key for gateway requests |
| `PROMPTFORGE_ADMIN_TOKEN` | Yes (for admin tools) | — | JWT token for secure mode, billing, providers, and audit tools |
| `PROMPTFORGE_ORG_ID` | Yes (for admin tools) | — | Default organization ID |
| `PROMPTFORGE_API_BASE` | No | `https://api.secureprompt.tech` | API base URL |
| `PROMPTFORGE_GATEWAY_URL` | No | `{API_BASE}/v1/gateway/requests` | Gateway endpoint override |
| `PROMPTFORGE_TIMEOUT` | No | `30` | Request timeout in seconds |
| `PROMPTFORGE_MCP_TOOLS_PATH` | No | — | Override path for tool definitions JSON |
| `MCP_RATE_LIMIT_PER_MINUTE` | No | `60` | Rate limit per minute |
| `MCP_TRANSPORT` | No | `stdio` | Transport mode (`stdio` or `http`) |
| `MCP_HOST` | No | `0.0.0.0` | SSE server host |
| `MCP_PORT` | No | `8765` | SSE server port |

## MCP Tools

### Gateway

| Tool | Description |
|---|---|
| `promptforge.secure_generate` | Send a request through the secure LLM gateway |
| `promptforge.list_gateway_requests` | List gateway request logs for an org (metadata only) |

### Secure Mode

| Tool | Description |
|---|---|
| `promptforge.redact_and_tokenize` | Tokenize sensitive entities in text |
| `promptforge.detokenize` | Restore tokenized text using a vault reference |
| `promptforge.list_secure_mode_entities` | List valid entity types for redaction |
| `promptforge.get_secure_mode_config` | Get org's Secure Mode configuration |

### Policies

| Tool | Description |
|---|---|
| `promptforge.policy_dry_run` | Evaluate a policy decision without executing a call |

### Audit

| Tool | Description |
|---|---|
| `promptforge.audit_query` | Query audit logs (admin-only) |

### Billing

| Tool | Description |
|---|---|
| `promptforge.get_billing_status` | Get billing status and usage metrics for an org |
| `promptforge.list_billing_plans` | List available billing plans |

### Providers

| Tool | Description |
|---|---|
| `promptforge.list_providers` | List configured LLM providers for an org |
| `promptforge.test_provider` | Test a provider connection and validate credentials |

## Docker

```bash
docker build -t promptforge-mcp .
docker run -p 8765:8765 \
  -e PROMPTFORGE_API_KEY=your-key \
  -e PROMPTFORGE_ORG_ID=your-org \
  -e PROMPTFORGE_ADMIN_TOKEN=your-token \
  promptforge-mcp --http
```

## License

MIT
