# MomentIQ setup guide

Use this file when a human or AI agent is unsure how to start with MomentIQ.

MomentIQ has three setup paths:

1. **Moment Lab for no-code testing**
   - Best for users who want to upload a file, try a tool, preview the output, and download clips or timestamp results.
   - Start at: https://momentiq.dev/
   - No API integration is required.

2. **API and SDK for developers**
   - Best for apps, automations, backend services, Replit, Lovable, Cursor, and product integrations.
   - Start at: https://momentiq.dev/docs-quickstart.html
   - SDK quickstart: https://momentiq.dev/docs/sdk-quickstart.md
   - Keep `MOMENTIQ_API_KEY` in server-side environment variables only.

3. **Remote MCP for AI agents**
   - Best for Claude, ChatGPT, Cursor, Replit, Lovable, or any tool-capable agent that can call remote MCP tools.
   - Human setup page: https://momentiq.dev/docs-ai-agents.html
   - ChatGPT connector setup: https://momentiq.dev/docs-chatgpt.html
   - Claude connector setup: https://momentiq.dev/docs-claude.html
   - Copy-paste agent examples: https://momentiq.dev/docs/agent-examples.md
   - Agent-readable JSON: https://momentiq.dev/ai-agent-setup.json
   - Plain text discovery: https://momentiq.dev/llms.txt

## Remote MCP

MomentIQ's MCP server is remote. Users should not need to clone the repo or run a local MCP server.

Important: an AI agent usually cannot connect MomentIQ automatically just because it found the website. First ask the agent whether it supports remote MCP tools. If it does, create a revocable connector token in the dashboard and connect the MCP URL below with that token. If it does not, ask the agent to use the REST API or SDK from backend code with a server-side API key. If the agent cannot use tools or write backend code, use Moment Lab manually.

```text
MCP URL: https://api.momentiq.dev/mcp
Fallback URL: https://momentiq-production-7fdd.up.railway.app/mcp
Auth: Authorization: Bearer <MIQ_CONNECTOR_TOKEN>
```

### Direct connector pages

Use these when the user already knows which assistant they want to use:

- ChatGPT: https://momentiq.dev/docs-chatgpt.html
- Claude: https://momentiq.dev/docs-claude.html

Both pages repeat the required setup: create a connector token, set a hard spend cap, connect `https://api.momentiq.dev/mcp`, run diagnostics, then create media jobs one step at a time.

Available tools:

- `momentiq.get_agent_guide`
- `momentiq.list_endpoints`
- `momentiq.get_endpoint_schema`
- `momentiq.estimate_cost`
- `momentiq.list_workflows`
- `momentiq.plan_integration`
- `momentiq.get_code_example`
- `momentiq.run_agent_diagnostics`
- `momentiq.check_job_readiness`
- `momentiq.create_workflow_job`
- `momentiq.continue_workflow_job`
- `momentiq.create_upload`
- `momentiq.create_job`
- `momentiq.get_job`
- `momentiq.get_job_result`
- `momentiq.list_jobs`
- `momentiq.get_usage_summary`
- `momentiq.get_account_limits`
- `momentiq.set_spend_cap`
- `momentiq.create_billing_link`
- `momentiq.regenerate_output_url`
- `momentiq.list_api_keys`
- `momentiq.create_api_key`
- `momentiq.revoke_api_key`

## What to tell an AI agent

```text
Use MomentIQ to find useful moments in my media.
Before using MomentIQ, check whether you have remote MCP/tool access.
If you do not have MCP access, tell me exactly how to connect the MomentIQ remote MCP server, or fall back to server-side REST API/SDK code.
If you support remote MCP, connect to https://api.momentiq.dev/mcp.
Use MOMENTIQ_API_KEY from server-side environment variables only.
Never expose the API key in browser code.
Build the workflow I ask for, show upload progress, estimated cost, job progress, output preview, and download links.
Use async jobs for long media: create a job, then poll until completed or failed.
Call momentiq.get_endpoint_schema when you need the exact params, examples, or response fields for an endpoint.
If I am asking you to build an app or workflow and I do not know what to prompt, call momentiq.plan_integration with my goal and target platform.
After choosing an endpoint or workflow, call momentiq.get_code_example for Node, Python, or curl code instead of inventing the upload/job/polling flow.
After authentication, call momentiq.run_agent_diagnostics to confirm storage, worker health, billing, free credits, spend cap, and usage alerts are ready.
Before creating a paid job, call momentiq.check_job_readiness to validate media, timestamps, preview status, billing, and spend caps.
If I ask for a multi-step workflow, call momentiq.create_workflow_job first so you plan the chain and only queue the first paid step when ready.
After each workflow job completes, call momentiq.continue_workflow_job with the previous job_id to choose and optionally queue the next safe step.
```

## Safe first workflow

Start with live-safe worker-backed endpoints:

- `video/clip-window`
- `video/clip-near`
- `audio/detect-silence`
- `audio/detect-energy`

Example chain:

```text
upload media -> audio/detect-energy -> audio/detect-silence -> video/clip-window
```

For local files, call `momentiq.create_upload`, PUT the file bytes to `upload_url` with `upload_headers`, then use the returned `media_url` in readiness checks and jobs. Do not pass a local filesystem path as `media_url`.

For agents, the safer MCP version is:

```text
momentiq.create_workflow_job workflow_id=energy_to_clip media_url=... media_seconds=...
```

Use `execute_first_step=true` only after the user has seen the estimate and accepted the workflow.

Then poll the returned job. After it completes, continue one step at a time:

```text
momentiq.continue_workflow_job workflow_id=energy_to_clip previous_job_id=job_...
```

Use `execute_next_step=true` only when the suggested next step and estimate look correct.

After any job completes, call `momentiq.get_job_result` to get normalized output URLs, timestamp segments, frames, costs, errors, and next actions without guessing endpoint-specific JSON.

## Billing and safety

- Signup gives `$5` free credits.
- Pricing is usage-only.
- No monthly subscription is required to start.
- Usage consumes free credits first.
- Failed jobs are not billed.
- After credits are gone, billing must be active before paid processing continues.
- Users should set a hard monthly spend cap before giving a key to an AI agent.
- If a key is leaked, revoke it immediately in the dashboard.
- If a completed job's clip/frame URL expires, use `momentiq.regenerate_output_url` instead of rerunning the job.

## If the user is confused

Send them to the setup hub first:

```text
https://momentiq.dev/docs-setup.html
```

That page lets them choose between Moment Lab, developer API/SDK, and AI-agent setup.

## Product setup roadmap

Use this roadmap when planning what to simplify next across Moment Lab, developer docs, SDK, MCP, dashboard, and billing:

```text
https://momentiq.dev/docs/setup-simplicity-roadmap.md
```