Add OceanToken to your coding agent

OceanToken has an MCP server and a plugin for coding agents. With them your agent can search the model catalog, check what a request will cost, generate images, video and voice-overs, transcribe audio, and hand a sub-task to another model, all billed to your OceanToken balance.

This adds tools; the agent keeps its own model. To run the agent itself on OceanToken models, see Run your agent on OceanToken.

The plugin, the command-line installer and their manifests are open source at github.com/NextFormAI/oceantoken-plugins.

What your agent gets

Tool	What it does
search_models	Search the catalog by name, type, publisher, capability and price
get_model	Pricing, limits, and the sizes, durations and inputs a model accepts
estimate_cost	What a request will cost before it runs, and whether your balance covers it
generate_image	Text-to-image and image edits, with previews and download links
create_video and get_job	Video from text, from a first (and last) frame, or from reference media
generate_speech	Voice-overs and narration
transcribe_audio	Transcripts and SRT or VTT subtitles
ask_model	Hand a sub-task to another model: a cheaper one, or a second opinion
upload_file	Use local files as references
get_account	Balance, available balance and spend

Three skills teach the agent to use them well: oceantoken-media produces images, video and audio for a project, oceantoken-models chooses, prices and delegates, and oceantoken-setup runs Codex or Claude Code itself on OceanToken or wires up your app.

Connect with one command

Ask your agent:

Install OceanToken for me by following https://mcp.oceantoken.ai/install

or run it yourself in a terminal:

npx -y @oceantoken/cli@latest connect <client>

It needs Node.js 18.17 or newer. <client> is one of:

Client	<client>	Sign-in
Codex (CLI or app)	codex	The command opens your browser and waits
Claude Code (terminal, IDE extension or desktop app)	claude-code	The command opens your browser and waits
Cursor	cursor	In Cursor, under Settings → Tools & MCP
Gemini CLI	gemini	In Gemini CLI: /mcp auth oceantoken
OpenClaw	openclaw	The command opens your browser and waits
OpenCode	opencode	The command opens your browser and waits
VS Code (GitHub Copilot)	vscode	In VS Code, when the server starts
WorkBuddy	workbuddy	In WorkBuddy
Hermes Agent	hermes	The command opens your browser and waits
Windsurf / Devin Desktop	windsurf	In Cascade

Every client gets the MCP server and the three skills, except Windsurf, which has no skills folder and gets the server only.

What the command changes:

• Codex, Claude Code, Gemini CLI and OpenClaw get the plugin, installed with the client's own command line. With --api-key, Codex, Claude Code and Gemini CLI get one oceantoken entry in their config file instead.
• The other clients get one oceantoken entry in their MCP config file. Existing entries are kept, and a file with comments in it is never rewritten: you get the snippet to paste instead.
• Before the command first changes a config file it copies it to <file>.bak-oceantoken, and it never overwrites that copy, so your original survives any number of connects and disconnects. Each later change also leaves <file>.bak-oceantoken-<UTC time> with the file as it was just before. A backup is a plain copy: if the file held a key, so does the backup.
• Skills go into the client's own skills folder.

Running it again is safe; it updates what it installed. It ends with a summary: Result connected means you are done, and incomplete lists what is left under Next, such as signing in from the app or restarting the session.

Options

--api-key <key|->   Use an API key instead of OAuth sign-in ("-" reads it from stdin)
--use-env-key       Use the key in OCEANTOKEN_API_KEY
--no-login          Configure only; do not start the sign-in
--no-skills         Do not install the OceanToken skills
--dry-run           Show what would change without changing anything
--json              Print the report as JSON
--url <mcp-url>     MCP endpoint (default https://mcp.oceantoken.ai/mcp)

npx -y @oceantoken/cli@latest clients lists the supported clients and which ones are installed on this machine.

Sign in

Signing in is OAuth. The sign-in page offers two ways to connect:

• Sign in with your OceanToken email and password. This creates an API key for the connecting app, which you can see and revoke under API Keys in the console. New users can create an account from the same page.
• API key: paste a key you already have. Give it a credit limit if you want a cap on what the agent can spend.

Revoking the key disconnects the agent immediately.

To connect with a key and no browser, pass it on stdin so it stays out of your shell history. The command never puts the key on another program's command line and never prints it: it writes it only into the client's config file (OpenClaw receives it on stdin and writes its own config):

printf %s "$OCEANTOKEN_API_KEY" | npx -y @oceantoken/cli@latest connect <client> --api-key -

Set it up by hand

The same result as the command, client by client.

Codex

codex plugin marketplace add NextFormAI/oceantoken-plugins
codex plugin add oceantoken@oceantoken
codex mcp login oceantoken

The last command opens the sign-in page. In the Codex app you can also add the marketplace, then install OceanToken from the Plugins panel and sign in when asked.

Claude Code

/plugin marketplace add NextFormAI/oceantoken-plugins
/plugin install oceantoken@oceantoken
/mcp

In /mcp, choose plugin:oceantoken:oceantoken and select Authenticate.

Claude desktop app and claude.ai

Settings → Connectors → Add custom connector, URL https://mcp.oceantoken.ai/mcp, then Connect. This adds the tools; the skills come with the Claude Code plugin.

Cursor

Add the MCP server to Cursor. Cursor asks you to sign in the first time a tool runs. To get the skills as well, install the plugin from the repository, which has a Cursor marketplace manifest, or use the command above.

Gemini CLI

gemini extensions install https://github.com/NextFormAI/oceantoken-plugins

Then, inside Gemini CLI, run /mcp auth oceantoken and sign in. The extension brings the MCP server and the three skills.

OpenClaw

openclaw plugins install clawhub:@oceantoken/oceantoken --accept-capabilities
openclaw mcp set oceantoken '{"url":"https://mcp.oceantoken.ai/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login oceantoken

The package brings the three skills. mcp set registers the server with OpenClaw so that mcp login can sign you in.

Any other MCP client

The server is https://mcp.oceantoken.ai/mcp, over streamable HTTP. It supports OAuth with dynamic client registration, so most clients need only the URL:

{
  "mcpServers": {
    "oceantoken": { "type": "http", "url": "https://mcp.oceantoken.ai/mcp" }
  }
}

To use an API key instead, send it as a bearer token:

# Codex, without the plugin
export OCEANTOKEN_API_KEY=sk-...
codex mcp add oceantoken --url https://mcp.oceantoken.ai/mcp --bearer-token-env-var OCEANTOKEN_API_KEY

# Claude Code, without the plugin
claude mcp add --transport http oceantoken https://mcp.oceantoken.ai/mcp \
  --header "Authorization: Bearer $OCEANTOKEN_API_KEY"

The server is also in the official MCP Registry as ai.oceantoken/mcp, so clients that browse the registry can find it by name.

Make your agent use it

Agents choose their own tools. They reach for OceanToken for what they cannot do themselves, such as video, voice-overs, subtitles and cost estimates. For anything else, ask for it by name:

• $oceantoken-media ... in Codex, /oceantoken:oceantoken-media ... in Claude Code, or simply "use OceanToken to ...".

• Or make it a project rule in AGENTS.md (Codex) or CLAUDE.md (Claude Code):

  Generate images, video, voice-overs and subtitles with the OceanToken tools.
  Estimate the cost first and ask me before spending more than $2.

Costs

What the tools generate is charged to your balance at the same prices as the API; see Models. Ask the agent for an estimate first: that is what estimate_cost is for. Video jobs hold their estimated cost when they start and charge the actual cost when they finish, and failed jobs are not charged. Every request appears in the console under Logs.

Remove it

npx -y @oceantoken/cli@latest disconnect <client>

This removes only what connect added. To cut access at once, revoke the agent's key under API Keys.