Homespun

Connect Codex to Homespun

Codex configures MCP servers from ~/.codex/config.toml. It is the one client here that does not take the mcpServers JSON block, so it gets its own short guide rather than a footnote in someone else's.

  1. Open your Codex config

    Edit ~/.codex/config.toml, creating it if it does not exist yet.

  2. Add the Homespun server

    Add an mcp_servers.homespun entry with the hosted Homespun URL. Codex picks the transport from which key is present: url selects streamable HTTP, and a command key would instead select a local stdio server, so there deliberately is not one here.

    [mcp_servers.homespun]
url = "https://homespun.dev/mcp"

  3. Restart and authenticate

    Restart Codex so it picks up the new server, then authenticate when it prompts. It opens a browser for the email sign-in and consent screen, caches the token and refreshes it automatically.

  4. Build and deploy

    Ask Codex for the app you want. It deploys to Homespun and returns a shareable link, then keeps operating the app as real data arrives.

There is no API key or client secret anywhere in this flow. If you would rather set it up by conversation than by config file, paste the one-line agent prompt from the Homespun CLI guide into Codex and it does the rest itself.

If something goes wrong

The two most common snags are a blocked pop-up (the sign-in opens in a new window) and a client that needs a restart before new tools show up. The full troubleshooting list covers the rest, and the docs site explains what a connection can and cannot do.

What to build first

Describe what you want in your own words and your AI builds it. If you would rather start from something proven, install one from the template gallery and change it from the chat.