Agent Host MCP

Turn your agent on the host into an MCP server.

Agent Host MCP lets your assistant work with the development environment on your Linux machine. Read project files, execute Python or shell commands, ask a remote Codex agent to carry out a task, and reuse knowledge from past sessions—all through one MCP connection.

Use it when your code lives on a remote host and you want your assistant to inspect that environment directly instead of copying files and terminal output into a conversation.

What you can do

• Understand a project: read contributor guidance, inspect files, and find saved Codex sessions.
• Get work done: run notebook-style Python cells or shell scripts, or delegate a task to Codex in a new or existing session.
• Keep useful context: build topic knowledge from sessions, then browse it in OpenWiki or search it from your assistant.
• Manage the host workflow: transfer files, label sessions, and inspect recorded token usage.

Quick start

1. Start Agent Host MCP on your host

You need a Linux host, uv, make, Node.js 22.22.0 or newer, and npm. Run the server as the account whose Codex sessions you want to use, with that account’s existing Codex login and configuration. Set CODEX_HOME if they live outside ~/.codex. A separate API key is not required by Agent Host MCP.

From a source checkout or an unpacked source release:

make build

Create a .env file in the directory from which you will start the server:

MCP_TOKEN=replace-with-a-long-random-secret

Replace the placeholder with a long, randomly generated token. Restrict access:

chmod 600 .env

Keep an existing .env when upgrading. Keep the token private and provide the same value to your client.

Start the server:

make run HOST=0.0.0.0 PORT=7081

The CLI is agent-host-mcp. After building, you can also start it directly:

./build/agent-host-mcp --host 0.0.0.0 --port 7081

Use the source-release setup above for all features, including OpenWiki. Installing the Python wheel alone does not set up the knowledge viewer.

2. Add it to your Codex client

On the machine where you use Codex, set MCP_TOKEN to your server’s token. For example, in Bash you can enter it without placing its value in shell history:

read -rsp 'Agent Host MCP token: ' MCP_TOKEN
export MCP_TOKEN
printf '\n'

Register the server, replacing https://YOUR_HOST with your server’s HTTPS URL:

codex mcp add remotecodex \
  --url https://YOUR_HOST/mcp \
  --bearer-token-env-var MCP_TOKEN

Start your Codex client from an environment where MCP_TOKEN is available. Other MCP clients can use Streamable HTTP at /mcp with Authorization: Bearer <MCP_TOKEN>.

3. Ask your assistant to use it

Try requests such as:

Use remotecodex to read AGENTS.md in my project directory and summarize its guidance.

Run a Python cell that calculates 6 * 7 on the remote host.

Start a new Codex session in my project and ask it to investigate the failing tests.

Search my saved knowledge for deployment hints.

Replace “my project directory” with the actual host path. The client discovers available tools and their parameters through tools/list.

Choose the right execution tool

Task	Tool	What to expect
Run code directly	execute(string, path="~")	A persistent Python namespace per directory. Variables, imports and functions carry over between cells.
Run a shell script	execute with a cell beginning with ! or %	The whole remaining cell runs through /bin/sh in the chosen directory.
Delegate work to Codex	run(path, prompt, session_id=None)	Omit the ID for a new saved session; supply one to resume that exact session.

execute defaults to the server account’s home directory. run requires an existing working directory. Use create_path to create an absolute directory and its missing parents first.

execute uses the server’s installed Python packages and normal account permissions; it is not a security sandbox. Python variables last until the runtime or server restarts. Shell environment/directory changes do not carry over to later cells. run uses your saved Codex login and configured defaults for new sessions. A saved session must be closed in its current Codex client before resuming it here.

Collect a long-running result

run, execute, build_knowledge, and delete_session return an action_id immediately. Save it, then repeat the same tool and original arguments with that ID until its status becomes completed, failed, or interrupted.

For example, start a cell:

{"string":"6 * 7"}

Then call execute again with the returned ID:

{"string":"6 * 7","action_id":"returned-action-id","wait_seconds":20}

Omitting the ID starts new work. Reconnecting never reruns the original task. Keep an omitted path or session_id omitted when reconnecting. Inspect the nested result.status too: a completed action may contain a failed cell or turn.

A gateway timeout or disconnected client leaves the job running. Each reconnect waits at most 20 seconds. SSE carries progress and the final result, rather than live stdout or model tokens. Server shutdown interrupts active jobs; they are not automatically rerun. Completed results are retained for up to 24 hours, subject to a 256-action capacity.

Build and use your knowledge

Ask your assistant to call list_models, choose a supported model and depth, then call build_knowledge. Supply session_id to target one session, or omit it for an incremental batch. Unchanged, verified context is reused.

Browse the results at /knowledge and sign in with your MCP token. The OpenWiki page and wiki_list_pages, wiki_search, and wiki_read tools use the same saved knowledge. Viewing or searching it does not call a model. Browser visualization needs access to OpenWiki’s pinned external library/font CDNs.

While the server runs, it also checks for new or changed session context every 30 minutes. When idle, it runs a daily maintenance pass that still skips unchanged context. Builds use your Codex login and can make model calls.

Session retirement: knowledge builds may delete sessions whose working directories have been removed, after saving and verifying their knowledge. Sessions with existing working directories are preserved by automatic builds. delete_session explicitly deletes a selected session, including one whose working directory exists, only after its current knowledge is verified. Active or changed sessions, and sessions with remaining descendants, are kept.

Available tools

The server exposes thirteen tools. See the detailed reference for schemas, limits, outputs and failure handling.

Tool	Use it to
list_sessions	Find saved session IDs, models, depths, working directories and descriptions.
update_session	Set a client-managed description; blank text clears it.
list_models	Discover supported models and reasoning depths.
create_path	Create an absolute host directory and missing parents.
execute	Execute Python cells or prefixed shell scripts.
run	Start or resume a Codex session and submit a prompt.
build_knowledge	Extract reusable knowledge from changed or selected sessions; may retire missing-directory sessions.
delete_session	Delete a session only after its current knowledge is saved and verified.
token_count	Inspect recorded host/session usage and cache-hit ratios; retired usage appears in others.
get_upload_skill	Get instructions for authenticated HTTP file uploads.
wiki_list_pages	Browse knowledge topic pages with pagination.
wiki_search	Find relevant knowledge sections.
wiki_read	Read selected sections and their source provenance.

To transfer a local file, read get_upload_skill first. Uploads use a separate HTTP POST /upload with the same Bearer token, the actual file bytes, and a client-selected absolute destination directory. Missing parents are created; existing files are never overwritten. The file limit is 100 MiB. Native MCP auth does not automatically expose the credential to an agent’s separate HTTP client.

Token usage is recorded session usage, not an exact billing report. Cached and reasoning counters are subsets, and cache_hit_ratio is cached input divided by input; unknown coverage is reported.

Access and upgrades

The landing page at / is public. MCP calls, uploads and knowledge content require authentication. Signing in to the knowledge browser does not authorize MCP calls or uploads. Connect only clients you trust with the host account’s access.

The server reads .env from its working directory; an exported MCP_TOKEN overrides the file. Restart the server after changing its token.

Keep your .env, Codex login and saved sessions when upgrading. Extracted knowledge is saved under ~/.agent-mcp/knowledge; preserve it and the other Agent Host MCP data described in the backup reference. Stop the previous service before starting its replacement on the same port, then refresh your client’s MCP connection to discover updated tools.

Check your setup

With the server running and curl installed:

make test PORT=7081

This checks the advertised tools, session/model discovery, token accounting and wiki retrieval. It does not submit model turns or delete real sessions. It prints session and model results, so keep that output private.

Symptom	What to check
Unauthorized or startup token error	Match the server’s token and the client’s MCP_TOKEN environment variable.
Port 7081 is already in use	Stop the intended previous process yourself, or choose another PORT.
Session has an active writer	Close its owning Codex session normally before resuming it, or omit the ID to create a separate session.
OpenWiki unavailable	Run make build from the source directory and check Node dependencies and browser CDN access.
Client still shows old tools	Refresh/reconnect the client after restarting the updated server; a new conversation alone may not refresh its cache.
Public gateway cannot be reached	Check gateway routing and any IP allowlist separately from the local server.

For detailed usage, limits and troubleshooting, see REFERENCE.md.