Connect ToolRouter to Codex

Written by Blake Folgado, last update:

Connect Codex to ToolRouter through terminal mcp + skill. Add the remote server, complete the advertised account flow and check a real tool call. One connection reaches the live catalog of hosted tools and provider operations.

Before you start

You need Codex with remote MCP enabled and permission to add a custom server. Workspace policy can restrict servers or actions. Free operations can be used without buying credits; paid operations need the account access and credits described by the response. Provider-account actions may need a separate connected account.

Connect ToolRouter

  1. Run the add command below.
  2. Run the login command and finish the browser sign-in.
  3. Check codex mcp list, then start a new Codex session in your project.
  4. For project instructions, install the skill below; it supplements the tools rather than granting account access.
bash
codex mcp add toolrouter --url https://api.toolrouter.com/mcp
codex mcp login toolrouter
codex mcp list

If the first call returns an account-claim or setup link, use that link to retain the account and unlock the operations you need. For OAuth clients, complete browser sign-in. Keep credentials in the client credential store rather than pasting tokens into a prompt or shared configuration.

Check a real result

Ask for a free, read-only first task:

Use ToolRouter to discover a free operation for current weather in London, run it, and show the tool, skill and every field returned.

The useful check is a successful provider result in this conversation. A saved server entry or a visible tool list only establishes configuration. If no operation is available through this profile, report that result rather than inventing a tool name.

Add live evidence to a local project

Codex can use the remote catalog alongside repository files. Ask it to collect the external evidence first, then update only the file you named. Use the same discovered input schema in a later pipeline rather than guessing field names.

Example prompt:

Use ToolRouter to inspect the public page I provide and compare its returned metadata with my local SEO note. Discover first, run the appropriate operation after checking price, retain the output and update only the named note.

This is a task template, not a recorded run. Review the sources or output asset before using it in a report.

Add the ToolRouter workflow skill

For a client that supports local skills, run the installer in your project and select the supported agent:

bash
pnpm dlx skills add Humanleap/agent-skills --skill toolrouter

The skill teaches discovery, schema checks, asynchronous jobs and source handling. It does not authenticate the account or add provider permissions. Your client documents these skill locations: .agents/skills/<skill>/SKILL.md; ~/.agents/skills/<skill>/SKILL.md.

The discovery and execution workflow

  1. Call discover with a query that describes the outcome: extract a page, research a company, check keyword demand, generate media or publish an authorised post.
  2. Select the returned tool and skill. Read the exact input schema, price, provider-account requirements and limitations.
  3. Call use_tool with that tool, skill and schema-matching input. Built-in tools are called directly; inspect the current tools/list first.
  4. If the response returns an asynchronous job handle, use the advertised status operation, such as job_get, until output is complete or an error is clear.
  5. Return original source URLs, completed asset links or the provider action result. Keep the retrieval date and any provider error visible.

A search operation and a social publishing operation have different authority and account requirements. An installed skill does not choose a provider or authorise a purchase for you.

Costs, accounts and recurring work

Read the discovered price and check credits_balance before a paid batch. Review pricing and billing; do not assume every provider uses the same charging unit. Account actions require the correct upstream account and permission for the actual post or message.

An MCP connection does not schedule a background agent. Use Codex's documented automation capability or your own scheduler for recurring jobs, with an explicit scope and budget. Check the previous job status before retrying an uncertain write.

Troubleshooting

The tools are missing

Enable the server for the conversation, reload MCP or restart the session, then check workspace policy. Configuration in a local editor does not automatically apply to a cloud agent.

Authentication or account access fails

Reconnect using the advertised OAuth flow, or use the returned account-claim link. A paid or provider-account operation can still fail after a free call works. Check the exact requirement returned by the tool.

The assistant answers without using ToolRouter

Ask it to name the actual operation and show returned fields or source URLs. A plausible answer without a tool result is not evidence of a provider call.

A job is queued or an action times out

Read the returned job status before repeating the call. A queued job is unfinished; an uncertain publishing response needs a status or provider readback before retrying.

Setup reviewed against the linked client documentation on 3 October 2026. Configuration instructions do not establish an authenticated end-to-end run in every client or an approved marketplace listing.