# iqprompt-mcp



Standalone [Model Context Protocol](https://modelcontextprotocol.io) server for [IQPROMPT](https://iqprompt.ai).



This repository is deployed independently (e.g. on Railway) and proxies MCP tool calls to the IQPROMPT HTTP API. By default it targets the **dev** environment:



`https://dev.iqprompt.ai`



## Architecture



```

MCP client (ChatGPT OAuth / Cursor Bearer)

        │  Streamable HTTP

        ▼

iqprompt-mcp (this service)

        │  X-API-Key (per user)

        ▼

dev.iqprompt.ai

  GET  /api/suggest/activity/recent

  POST /api/suggest/suggest-prompt

  POST /api/suggest/session/new

```



## Tools



| Tool | Upstream endpoint |

|------|-------------------|

| `test_connection` | `GET /api/suggest/activity/recent` |

| `enhance_prompt` | `POST /api/suggest/suggest-prompt` |

| `enhance_for_coding_agent` | `POST /api/suggest/suggest-prompt` (`category=coding_agent`) |

| `create_session` | `POST /api/suggest/session/new` |

`enhance_for_coding_agent` always sends `category=coding_agent`. Prefer it over
`enhance_prompt` when rewriting prompts for coding agents.

`enhance_prompt` / `enhance_for_coding_agent` reuse the upstream session ID
returned for the same API key and `end_user_email`. A new session is created only
for the first enhancement in that scope, after an explicit `create_session`, or
when `session_action` is `reset`. Session reuse is process-local, so a redeploy
or multi-instance deployment requires the caller to pass `session_id` for durable
continuity.

`test_connection` uses the read-only activity endpoint to verify API key validity
without generating a prompt or creating a session.



## Authentication



### ChatGPT (OAuth + paste API key)



1. In ChatGPT, add a custom MCP connector pointing at `https://mcp.iqprompt.ai/mcp` with **OAuth**.

2. ChatGPT opens the IQPROMPT connect page.

3. User signs up / logs in at [iqprompt.ai](https://iqprompt.ai), copies their API key, and pastes it on the connect page.

4. MCP issues an OAuth access token bound to that key and uses it for `/api/suggest`.



### Cursor / Claude Desktop (Bearer API key)



Pass your IQPROMPT API key as a Bearer token (OAuth-protected `/mcp` requires `Authorization`):



```json

{

  "mcpServers": {

    "iqprompt": {

      "url": "https://mcp.iqprompt.ai/mcp",

      "headers": {

        "Authorization": "Bearer iq_your_api_key"

      }

    }

  }

}

```



Do **not** set a shared `IQPROMPT_API_KEY` on Railway for multi-user deployments.



## Local development



```bash

python -m venv .venv

.venv\Scripts\activate          # Windows

# source .venv/bin/activate     # macOS/Linux



pip install -r requirements.txt

pip install -e .



copy .env.example .env

# set MCP_PUBLIC_URL=http://localhost:8100

python -m iqprompt_mcp

```



| Endpoint | Purpose |

|----------|---------|

| `http://localhost:8100/mcp` | MCP Streamable HTTP |

| `http://localhost:8100/connect` | Paste API key (OAuth authorize UI) |

| `http://localhost:8100/health` | Health check |

| `http://localhost:8100/.well-known/oauth-authorization-server` | OAuth discovery |


## Verification

Run the local unit tests after installing the project dependencies:

```bash
python -m unittest discover -s tests -q
```

Run a deployed-service smoke test with a valid IQPROMPT API key. The script checks
`/health`, MCP initialization, tool discovery, and `test_connection`:

```powershell
$env:IQPROMPT_API_KEY = "iq_your_api_key"
python tools/smoke_test.py --mcp-url https://mcp.iqprompt.ai/mcp
```



## Deploy to Railway



1. Create a new Railway project from this repository.

2. Railway builds with `Dockerfile` (see `railway.toml`).

3. Set environment variables:



| Variable | Value |

|----------|-------|

| `IQPROMPT_API_URL` | `https://dev.iqprompt.ai` |

| `MCP_PUBLIC_URL` | `https://mcp.iqprompt.ai` |

| `IQPROMPT_DASHBOARD_URL` | `https://iqprompt.ai` |

| `OAUTH_ENABLED` | `true` |



`PORT` is injected automatically by Railway.



4. Point ChatGPT at `https://mcp.iqprompt.ai/mcp` with OAuth authentication.



### Production API



When ready for production upstream:



```

IQPROMPT_API_URL=https://api.iqprompt.ai

```



(Use your actual production API host if different.)



## Environment variables



| Variable | Default | Description |

|----------|---------|-------------|

| `IQPROMPT_API_URL` | `https://dev.iqprompt.ai` | Upstream IQPROMPT API base URL |

| `IQPROMPT_DASHBOARD_URL` | `https://iqprompt.ai` | Login / signup / API key UI links |

| `MCP_PUBLIC_URL` | `http://localhost:8100` | Public base URL of this MCP server (OAuth issuer) |

| `OAUTH_ENABLED` | `true` | Enable OAuth + `/connect` paste-key flow |

| `IQPROMPT_API_KEY` | — | Optional local fallback only |

| `MCP_HOST` | `0.0.0.0` | Bind host |

| `PORT` / `MCP_PORT` | `8100` | Listen port |



## Notes



- OAuth client registrations, codes, and tokens are stored **in memory**. Users may need to reconnect after a Railway redeploy.

- Raw `iq_…` keys sent as `Authorization: Bearer` are accepted so Cursor works without the browser flow.



## Docker



```bash

docker build -t iqprompt-mcp .

docker run --rm -p 8100:8100 \

  -e IQPROMPT_API_URL=https://dev.iqprompt.ai \

  -e MCP_PUBLIC_URL=http://localhost:8100 \

  iqprompt-mcp

```



## Repository note



This folder can live inside the main IQPROMPT monorepo during development, but it is intended to be hosted as its **own** Railway service and may be split into a separate Git repository when you are ready.