# MomentIQ.dev Public MCP Connector Plan

MomentIQ already exposes a private/beta remote MCP server at:

- `https://api.momentiq.dev/mcp`
- fallback: `https://momentiq-production-7fdd.up.railway.app/mcp`

The current beta auth model is a revocable MomentIQ connector token created from the dashboard. This lets ChatGPT, Claude, Cursor, Replit, Lovable, or a backend agent use MomentIQ without exposing normal API keys.

## Current State

Implemented:

- Remote JSON-RPC MCP endpoint: `POST /mcp`
- Public MCP discovery: `GET /mcp`, `GET /mcp/manifest`, `GET /mcp/status`
- Well-known metadata:
  - `/.well-known/mcp.json`
  - `/.well-known/oauth-protected-resource`
  - `/.well-known/oauth-authorization-server`
- Manual connector-token auth:
  - `POST /api/dashboard/connectors`
  - `GET /api/dashboard/connectors`
  - `POST /api/dashboard/connectors/{token_id}/revoke`
- Scoped connector tokens:
  - `all`
  - `video/*`
  - `audio/*`
  - `timeline/*`
- Safe public MCP tools that do not spend credits.
- Authenticated paid tools protected by account credits, billing, spend caps, and key revocation.
- Connector brand assets:
  - App icon: `https://momentiq.dev/assets/brand/app-icon-512.png`
  - Horizontal logo: `https://momentiq.dev/assets/brand/logo-horizontal-light.png`
  - Social image: `https://momentiq.dev/assets/brand/og-image-1200x630.png`
- Review-facing ChatGPT submission draft:
  - `chatgpt-app-submission.json`
- Explicit MCP tool annotations:
  - `readOnlyHint`
  - `openWorldHint`
  - `destructiveHint`

Not public-listed yet:

- OpenAI public connector listing.
- Anthropic public connector listing.
- Provider-approved OAuth client IDs and redirect URIs.
- Public connector marketplace review and approval.
- Formal review of privacy, terms, and data-retention language.

## Phase 1: Private MCP Validation

Status: implemented.

Validation checklist:

- `POST /mcp` with `initialize` returns server info.
- `POST /mcp` with `tools/list` returns MomentIQ tools.
- Public tools work without auth:
  - `momentiq.get_agent_guide`
  - `momentiq.list_endpoints`
  - `momentiq.get_endpoint_schema`
  - `momentiq.estimate_cost`
  - `momentiq.list_workflows`
  - `momentiq.plan_integration`
  - `momentiq.get_code_example`
- Connector-token tools work with `Authorization: Bearer miq_conn_...`.
- Revoked connector tokens return `invalid_api_key`.
- Scoped connector tokens enforce `connector_scope_denied`.

## Phase 2: Public Connector Authentication

Status: OAuth scaffold implemented; owner/provider client configuration required.

MomentIQ publishes protected-resource and authorization-server metadata so connector reviewers and agents can discover the intended public connector model. The authorization-code endpoints exist at:

- `GET /api/auth/oauth/authorize`
- `POST /api/auth/oauth/token`
- `GET /api/auth/oauth/clients`

These endpoints only issue connector tokens when the API service has approved provider client IDs and exact redirect URIs configured through Railway environment variables. Without that configuration, OAuth returns `server_error` with a clear "not configured" message.

Recommended public model:

1. User clicks "Connect MomentIQ" inside ChatGPT or Claude.
2. Provider opens MomentIQ authorization screen.
3. User signs in with Google, GitHub, or email.
4. User approves a connector scope:
   - `all`
   - `video/*`
   - `audio/*`
   - `timeline/*`
5. MomentIQ issues a connector access token scoped to that user account.
6. ChatGPT/Claude calls `/mcp` using that token.

Keep manual connector tokens for private testing even after OAuth exists.

Railway env options:

```env
MOMENTIQ_CONNECTOR_OAUTH_CLIENTS=[{"client_id":"...","name":"ChatGPT","connector":"chatgpt","redirect_uris":["https://..."]}]
```

or the simpler single-client form:

```env
MOMENTIQ_CONNECTOR_OAUTH_CLIENT_ID=...
MOMENTIQ_CONNECTOR_OAUTH_CLIENT_NAME=ChatGPT
MOMENTIQ_CONNECTOR_OAUTH_CONNECTOR=chatgpt
MOMENTIQ_CONNECTOR_OAUTH_REDIRECT_URIS=https://example.com/callback,https://example.com/another-callback
```

## Phase 3: Public Connector Package

Needed from owner before submission:

- Final connector name.
- Final short description.
- Final long description.
- Square icon/logo.
- Support email.
- Privacy policy URL.
- Terms URL.
- Data retention language.
- Media deletion policy.
- Billing/free-credit wording.
- Final production API domain.

Recommended copy:

- Name: `MomentIQ.dev`
- Short description: `Find timestamped moments in video and audio for AI apps.`
- Long description: `MomentIQ.dev gives AI agents and developers media timeline tools for uploads, cost estimates, job creation, polling, output URLs, clips, silence, energy, frames, and structured timeline results.`
- Category: developer tools, media, productivity, AI.

## Phase 4: Safety And Billing Review

Already implemented or documented:

- Cost estimation before paid jobs.
- Spend caps.
- Usage alerts.
- Free credits.
- Billing-required gating.
- Revoked key enforcement.
- Scoped connector tokens.
- Failed jobs are not billed.
- Output URL regeneration instead of rerunning completed jobs.

Before public launch, confirm:

- Upload retention period.
- Result retention period.
- User deletion flow.
- Support process for accidental uploads.
- Live Stripe billing behavior.
- Production logging does not include secrets or full media URLs when avoidable.

## Phase 5: Submission

Owner-only tasks:

- Submit the connector from the official OpenAI/ChatGPT owner account.
- Submit the connector from the official Anthropic/Claude owner account if public listing is available.
- Use MomentIQ.dev production docs, privacy, and terms URLs.
- Forward review feedback into the repo as issues or notes.

Codex/code tasks after feedback:

- Adjust OAuth details.
- Adjust tool descriptions.
- Adjust privacy/billing language.
- Add provider-specific metadata if required.
- Add review-specific tests.

## Phase 6: Launch Monitoring

Monitor:

- MCP `initialize` and `tools/list` success rate.
- Paid tool errors.
- `billing_required` counts.
- `connector_scope_denied` counts.
- Revoked-token attempts.
- Worker queue age.
- Failed jobs by endpoint.
- Usage and revenue by connector.

Useful admin views:

- Top MCP users by spend.
- Top MCP users by failed jobs.
- Most-used MCP tools.
- Most common readiness warnings.
- Workflows that create the most clips.