Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown
Browse docs

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown

Codex

Set up Expand for Codex with the Expand Skill and MCP tools.

Install the Expand Skill so Codex knows when to use Expand, then install MCP so Codex can call Expand Fetch tools directly. Codex uses both: the skill teaches intent, MCP provides the tools. Codex has no Expand hook path.

expandai login
expandai skill install codex project
expandai mcp install codex project

Run this from your project root. Project setup writes .agents/skills/expandai/ and .codex/config.toml. If Codex does not pick up the new skill or MCP server, restart or reopen Codex.

MCP verification prompt:

Use the Expand MCP fetch tool to fetch https://news.ycombinator.com.
Show me the first 10 lines of Markdown and confirm the Fetch succeeded.

If MCP is not wired up yet, the skill can still drive the CLI. Cross-agent check:

Use Expand to fetch https://news.ycombinator.com.
Show me the first 10 lines of Markdown and confirm the Fetch succeeded.

Optional local auth check:

expandai whoami

What gets installed

PieceWhat it does
Expand SkillInstalls SKILL.md so Codex knows when to use Expand and how to fall back to the CLI.
MCP serverRegisters the Expand MCP server as expandai, run with expandai mcp run.
Shared authCodex config does not receive API keys. The MCP server reads local Expand CLI auth from expandai login.

Codex does not have an Expand hook path. For Codex, install both Skill and MCP.

Project and global scope

Project scope is the default. It keeps Expand scoped to one repo and lets you commit the config for collaborators.

ScopeInstall commandsWrites toWhen to use
Projectexpandai skill install codex project
expandai mcp install codex project		<project root>/.agents/skills/expandai/
<project root>/.codex/config.toml		Recommended for one repo.
Global

Codex uses .agents/skills/expandai/ for skills, not .codex/skills/expandai/.

Commit project-scoped .agents/skills/expandai/ and .codex/config.toml only if the team wants Expand enabled for collaborators.

If Codex ignores project config, make sure the project is trusted in Codex.

Skill and MCP

The skill gives Codex instructions for when to use Expand. MCP gives Codex native tools such as fetch and fetch_search.

Skill alone can work when Codex can run shell commands. Add MCP when you want Codex to call Expand as native tools. For Codex, install both. Codex does not have an Expand hook path, so there is no automatic interception of its built-in fetching.

What the installer writes

This is a reference for debugging. The installer writes these for you, and you usually should not edit them by hand.

Skill path:

<project root>/.agents/skills/expandai/SKILL.md

MCP config shape in .codex/config.toml:

[mcp_servers.expandai]
command = "expandai"
args = ["mcp", "run"]
enabled = true

The installed MCP server runs without --docs, so the optional expand:// docs resources are not exposed by default. To expose them, see MCP Tools & Resources.

Uninstall

Uninstall both pieces if you want Codex to forget the Expand instructions and remove the native MCP tools.

expandai skill uninstall codex project
expandai mcp uninstall codex project

Global uninstall:

expandai skill uninstall codex global
expandai mcp uninstall codex global

Troubleshooting

Codex does not see the skill

  • Confirm the skill was installed for the same scope Codex is using.
  • Confirm <project root>/.agents/skills/expandai/SKILL.md exists for project setup.
  • Do not look for the skill under .codex/skills/.
  • Restart or reopen Codex if it does not reload skills.

MCP tools are missing

  • Confirm <project root>/.codex/config.toml contains [mcp_servers.expandai] for project setup.
  • Confirm ~/.codex/config.toml contains [mcp_servers.expandai] for global setup.
  • Restart or reopen Codex.
  • Use Codex MCP inspection, such as /mcp, if available.

Project config is ignored

Codex may ignore project config until the project is trusted. Trust the project, then restart or reopen Codex.

Config landed in the wrong place

Expand writes project-scoped Codex config to your current directory, not a detected repo root. If Codex cannot find the skill or MCP server, confirm you ran the install commands from the project root and check where .codex/config.toml and .agents/skills/expandai/ actually landed.

Fetch fails or auth is missing

Run expandai login and expandai whoami in your terminal, then try the verification prompt again. Do not paste API keys into Codex config.

Codex does not use the tool

Ask Codex explicitly to use the Expand MCP fetch tool, then retry.

Next steps

  • Agent Quickstarts overview
  • Expand Skill
  • MCP Tools & Resources
  • CLI Commands
PreviousCursor
NextOpenCode

On This Page

What gets installedProject and global scopeSkill and MCPWhat the installer writesUninstallTroubleshootingCodex does not see the skillMCP tools are missingProject config is ignoredConfig landed in the wrong placeFetch fails or auth is missingCodex does not use the toolNext steps
expandai skill install codex global

expandai mcp install codex global
~/.agents/skills/expandai/
~/.codex/config.toml
Use Expand across projects.