Loading skill
Loading skill
moatlight-connectMoatlight · published in Moatlight/moatlight-agent-kit
Picks the right path (sandbox, MCP, CLI, SDK or REST), logs in with OAuth and explains every 401, 402, 403 and 429.
Agents keep only this description in mind and load the skill when a request matches it. It is the exact text from SKILL.md.
Connect an agent to Moatlight: pick the access path (no-login sandbox, MCP server, CLI, SDK or REST), log in with OAuth, and fix 401, 402, 403 and 429 answers. Use when the user wants to use Moatlight from an agent or script, asks how to authenticate or which scopes to request, or a Moatlight call fails with an auth, plan or rate limit error.
Made-up data with the same shapes as production, no login.
Authorization code with PKCE, asking only for the scopes the job needs.
Each one is JSON with a code and a hint, read before any retry.
After installing, say it in your own words. For example:
Everything the skill contains. Each file opens as plain text on this site; the same files are on GitHub.
--- name: moatlight-connect description: "Connect an agent to Moatlight: pick the access path (no-login sandbox, MCP server, CLI, SDK or REST), log in with OAuth, and fix 401, 402, 403 and 429 answers. Use when the user wants to use Moatlight from an agent or script, asks how to authenticate or which scopes to request, or a Moatlight call fails with an auth, plan or rate limit error." license: MIT compatibility: "Needs network access to moatlight.com. Works in any agent that can make HTTPS calls or use an MCP server." metadata: author: Moatlight version: "1.2.1" homepage: https://moatlight.com/docs --- # Connect to Moatlight ## Pick the path | Need | Use | |---|---| | Try it with made-up data, no login | `https://moatlight.com/api/v1/sandbox` (same shapes as production) | | Agent client with tools | MCP server `https://moatlight.com/mcp` (Streamable HTTP, OAuth). Docs search without login: `https://moatlight.com/mcp/docs` | | Shell or CI | `npx @moatlight/cli product` (JSON on stdout, exit 0 ok, 1 API error, 2 usage) | | Code | `@moatlight/sdk` (npm) or `moatlight` (PyPI) | | Anything else | REST, spec at https://moatlight.com/openapi.json | Start on the sandbox. Move to production only when the user wants real data. ## Log in 1. OAuth 2.0 authorization code with PKCE. Full steps: https://moatlight.com/auth.md. 2. Ask only for the scopes the job needs: `account:read`, `reports:read`, `reports:write`, `agent-readiness:read`, `agent-readiness:scan`. 3. Claude Code: `claude mcp add --transport http moatlight https://moatlight.com/mcp`, then `/mcp` and choose moatlight. Codex: `codex mcp add moatlight --url https://moatlight.com/mcp`. 4. Check with `GET https://moatlight.com/api/v1/me`. It returns `plan` and `limits`. ## Errors Every error is JSON with `code`, `message` and `hint`. Read `hint` before retrying. - `401 invalid_token`: the token expired or the server changed. Use the refresh token, or reconnect. Do not retry the same token. - `402 needs_early_access_pass`: a person must buy the pass at https://moatlight.com/pricing. Give them `upgrade_url`. You cannot pay. - `403 insufficient_scope`: the token lacks `required_scope`. Ask the user to approve it, then log in again. `403 domain_cap` is the free plan limit instead. - `429`: wait `Retry-After` seconds. `RateLimit` headers show what is left. Do not loop. ## Gotchas - Send an `Idempotency-Key` header on every POST so a retry cannot start a second report. The SDKs do this. - Lists are cursor-paged: pass `next_cursor` back as `cursor` until `has_more` is false. - A `202` answer means a job is still running. Follow `status_url` and honor `Retry-After`. - There is no API key. Never ask the user to paste a secret into the chat. ## Do not - Do not start a report to test the connection. It uses the user's allowance. Call `/me` or the sandbox.
Found a problem in this skill? Open an issue on GitHub or write to Moatlight.
