--- name: connect description: Connect to loader.land's MCP server by OAuth, or use the HTTP API with a key or a management session, then check who you are. --- # Connect The MCP server is `https://api.billing-test.loader.land/mcp` (streamable HTTP, stateless). ## Name the server after yourself Several agents can share one computer, and they can see each other's MCP settings and stored OAuth credentials. If you were paired, register the MCP server under the exact name your pairing prompt gives you (for example `loader--k3x9`): it belongs to you alone, so an existing entry with that exact name is your own earlier connection — update its Authorization header. Without a pairing prompt (Way A), name it `loader--<4 random letters or digits>`, such as `loader-mysite-q7f2`. Do not use a plain `loader-`: Claude Code keeps the OAuth credentials of every directory in one file, keyed by server name and URL, so two agents that pick the same name overwrite each other's login even in different directories. Either way, do not remove or overwrite entries with other names: they may be other agents' connections. Scope: Claude Code's default scope is local (this directory only); add the server again in another directory with the same name, and do not install it at user scope. Grok CLI: add `--scope project`. Codex has no project option (`codex mcp add` reports "Added global MCP server"); that is fine, because the door plate below tells agents apart. Other MCP clients follow the same rules. One agent per folder: the door plate can name only one connection. If your owner wants two agents on the same code, give each its own folder (for example a `git worktree`). ## Leave a door plate Once connected, add one line to `AGENTS.md` in the project root (Claude Code reads `CLAUDE.md`, so use that instead): ``` This folder's loader.land connection is (agent ID ); use only this one, other loader-* entries belong to other agents on this computer. ``` Write the server name and agent ID, never the token. A paired agent finds its ID in the pair response (`agent.id`); an OAuth agent gets it from its first `whoami`. At the start of every session, call `whoami` through the server the plate names and compare `auth.agent.id` with the plate. If they differ, or the plate names a server you do not have, stop and ask your owner; do not act through another agent's connection. ## Way A: OAuth, when you can open a browser Add the server to your MCP settings. Claude Code: ``` claude mcp add --transport http loader-- https://api.billing-test.loader.land/mcp ``` The first tool call opens a browser; your owner signs in, names you (or reconnects an agent they already have) and approves. Request all three scopes when you connect: `sites:read sites:stage sites:publish`. Right after connecting call `whoami`; if `can_publish` is `false`, your owner made you draft-only: work normally and follow "Draft-only agents" in [workflow](../workflow/SKILL.md) when `publish_release` is refused. ## Way B: a pair code, when you cannot open a browser Your owner opens `https://app.billing-test.loader.land/agents`, names you and copies a prompt that already contains a one-time code such as `K7M2-Q9XD` (valid 10 minutes, single use). New agents may publish; your owner can narrow that later. Exchange the code once: ``` curl -sS -X POST https://api.billing-test.loader.land/v2/agents/pair -H 'content-type: application/json' -d '{"code":"K7M2-Q9XD"}' ``` The response is `{"token", "agent": {"id", "display_name"}, "mcp_url", "guide"}`. Send the token as `Authorization: Bearer ` on every MCP request. Claude Code: ``` claude mcp add --transport http https://api.billing-test.loader.land/mcp --header "Authorization: Bearer " ``` The token is your owner's authority: never print it, never write it to a file or to version control; keep it only in the MCP settings. It also works as the Bearer on the HTTP API (`https://api.billing-test.loader.land/v2/...`), which is how you upload large bundles (see [sites](../../publish/sites/SKILL.md)). It does not expire while you use it; after 90 idle days it stops working and your owner pairs you again. Any failure is `400 invalid_pair_code` (wrong, used or expired): do not retry; ask your owner to press 重新配對 for you at `https://app.billing-test.loader.land/agents` and paste the new prompt. `409 quota_exceeded` means your owner already has as many agents as the plan allows. ## Way C: deployment key or management session Older setups use a deployment key from `https://app.billing-test.loader.land/account#keys` as `Authorization: Bearer ` on `https://api.billing-test.loader.land`. It carries your owner's full authority and is recorded only by its label; prefer Way A or B. The HTTP-only management session is described in [sites](../../publish/sites/SKILL.md). ## A local agent skill A small entry card that tells you to read this guide (llms.txt, then the site-skills catalog) at the right moment. Agents that follow the shared Agent Skills folder (Codex, Gemini CLI, Cursor and others) read `~/.agents/skills`; Claude Code reads `~/.claude/skills`. Install it where your agent looks: ``` mkdir -p ~/.agents/skills/loader-land && curl -so ~/.agents/skills/loader-land/SKILL.md https://billing-test.loader.land/site-skills/start/connect/agent-skill.md mkdir -p ~/.claude/skills/loader-land && curl -so ~/.claude/skills/loader-land/SKILL.md https://billing-test.loader.land/site-skills/start/connect/agent-skill.md ``` ## First call Call `whoami` (HTTP: `GET /v2/whoami`) and check `auth.agent.id` against your door plate. `auth.agent` is who you are (id, display_name, permission); it also names your owner, the project your credential is bound to (whoami shows its name), the plan with its limits and usage, whether you may publish, and this guide's address. Then read [workflow](../workflow/SKILL.md).