# Set up OmniLink — instructions for coding agents

You are a coding agent (Claude Code, Codex, Cursor, VS Code, Gemini CLI or
similar) and a person asked you to set up OmniLink for them. Follow these
steps in order. The person only has to click one link and press Approve.

OmniLink runs AI agents that act through tools, including robots in OmniSim,
a free open-source robotics simulator. You drive the account through the
OmniLink MCP server at `https://www.omnilink-agents.com/api/mcp`.

## Rules

- **The OmniKey is a secret.** It gives full access to the person's account.
  Store it only in their MCP client's user config or a user environment
  variable (`OMNI_KEY`). Never write it into a repository, a project file that
  gets committed, a log, or a chat reply.
- **Provider keys are secrets too.** Only save a model-provider key the person
  gave you for this purpose. OmniLink never returns it after saving.
- **Ask before deleting anything.** Every `delete_*` and `remove_*` tool is
  permanent. Standing orders and watches can be paused instead.

## 1. Get an OmniKey (one click from the person)

If your MCP client can add a server without a key, add the server first (step
2, without the header) and call the `connect_account` tool, then
`finish_connect`. Otherwise use plain HTTP:

```bash
curl -s -X POST https://www.omnilink-agents.com/api/agent-connect/start \
  -H "Content-Type: application/json" -d '{"client":"Claude Code"}'
```

The reply has `verification_uri_complete`, `user_code` and `device_code`.

1. Show the person the link and the code, for example: "Open
   https://www.omnilink-agents.com/agents/connect/ABCD-EFGH, sign in with
   Google or GitHub, and press Approve. The code should read ABCD-EFGH."
   A free account is created if they don't have one.
2. Every 5 seconds, collect the key:

```bash
curl -s -X POST https://www.omnilink-agents.com/api/agent-connect/token \
  -H "Content-Type: application/json" -d '{"device_code":"<device_code>"}'
```

- `{"error":"authorization_pending"}`: keep waiting.
- `{"error":"slow_down"}`: wait longer between polls.
- `{"error":"expired_token"}`: the code is older than 10 minutes. Start again.
- `{"omni_key":"olink_..."}`: done. **It is shown once.** Store it as below
  right away, without printing it.

Keep `device_code` private while you wait; it is what collects the key.

## 2. Add the MCP server

Endpoint: `https://www.omnilink-agents.com/api/mcp` (Streamable HTTP).
Header: `Authorization: Bearer <OmniKey>`.

**Claude Code**

```bash
claude mcp add --transport http omnilink https://www.omnilink-agents.com/api/mcp --header "Authorization: Bearer $OMNI_KEY"
```

This stores the key in the person's user config. For a shared `.mcp.json`,
write `"Authorization": "Bearer ${OMNI_KEY}"` so the file holds only the
variable name.

**Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.omnilink]
url = "https://www.omnilink-agents.com/api/mcp"
bearer_token_env_var = "OMNI_KEY"
```

**Cursor** (`~/.cursor/mcp.json`)

```json
{ "mcpServers": { "omnilink": {
  "url": "https://www.omnilink-agents.com/api/mcp",
  "headers": { "Authorization": "Bearer ${env:OMNI_KEY}" } } } }
```

**VS Code** (`.vscode/mcp.json`; VS Code asks for the key and stores it securely)

```json
{ "inputs": [ { "type": "promptString", "id": "omni-key", "description": "OmniKey", "password": true } ],
  "servers": { "omnilink": { "type": "http",
    "url": "https://www.omnilink-agents.com/api/mcp",
    "headers": { "Authorization": "Bearer ${input:omni-key}" } } } }
```

**Gemini CLI** (`~/.gemini/settings.json`)

```json
{ "mcpServers": { "omnilink": {
  "httpUrl": "https://www.omnilink-agents.com/api/mcp",
  "headers": { "Authorization": "Bearer $OMNI_KEY" } } } }
```

**Any other client**: the URL and header above. Clients that read `OMNI_KEY`
from the environment need it set for the person's user (Windows:
`setx OMNI_KEY <key>`, then a new terminal; macOS and Linux: the shell
profile). Most clients need a restart or reconnect to pick up a new server.

**No MCP support?** Call the same endpoint as JSON-RPC:

```bash
curl -s https://www.omnilink-agents.com/api/mcp -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account_status","arguments":{}}}'
```

## 3. Check what is set up

Call `get_account_status`. It returns the plan, agents, which model providers
have a key (never the keys), which robots are online, and `nextSteps`. Do the
next steps it lists:

- **No provider key**: agents need the person's own model key (Google Gemini,
  OpenAI, Anthropic, xAI or OpenRouter; the provider bills them directly). Ask
  for one and call `add_provider_key`, or send them to
  https://www.omnilink-agents.com/agents/start to paste it there.
- **No robot online**: install OmniSim from
  https://github.com/omnilink-tech/omnisim (its `AGENTS.md` is written for
  you), then run a chat demo with `OMNI_KEY` set:
  `python -m omnisim run-world projects/samples/demos/worlds/chat/omnilink_husky.omniworld`.
  The robot registers as `OmniSim-husky` within about 30 seconds. Windows has
  a prebuilt package; Linux builds from source.

## 4. Use it

| Need | Tools |
|---|---|
| Sign in | `connect_account`, `finish_connect` |
| Status and setup | `get_account_status`, `list_provider_keys`, `add_provider_key`, `remove_provider_key`, `list_robots` |
| Agents | `list_agents`, `create_agent`, `update_agent`, `delete_agent` |
| Talk | `send_robot_prompt` (one sentence to a robot; its reply comes back verbatim), `chat` |
| Conversations | `list_conversations`, `create_conversation`, `update_conversation`, `delete_conversation`, `list_messages`, `send_message` |
| Schedules | `list_standing_orders`, `get_standing_order`, `create_standing_order`, `update_standing_order`, `delete_standing_order` |
| Watches | `list_watches`, `create_watch`, `update_watch`, `delete_watch` |
| Usage | `get_key_usage`, `get_agent_costs`, `get_fleet_overview` (Master plan and up) |

A good first instruction: `send_robot_prompt` with `agentName` `OmniSim-husky`
and `text` "drive forward one metre, then tell me what you did".

## Limits and what is not offered

- Plan limits apply exactly as on the website. Pricing:
  https://www.omnilink-agents.com/pricing
- Not available to agents: billing, creating or revoking keys with a key, and
  admin functions. The person manages those at
  https://www.omnilink-agents.com/dashboard?view=api
- Nothing here has been run on a physical robot. OmniSim is a simulator.