iqprompt-mcp

Standalone Model Context Protocol server for IQPROMPT.

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

Related MCP server: FastMCP Example Server

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, 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):

{

  "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

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:

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:

$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

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.