Metadata-Version: 2.5
Name: agent-host-mcp
Version: 0.1.1
Summary: Connect Codex sessions, remote execution, and project knowledge to MCP clients.
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.12
Requires-Dist: openai-codex>=0.167.0
Requires-Dist: python-dotenv<2,>=1
Requires-Dist: python-multipart<1,>=0.0.33
Description-Content-Type: text/markdown

# 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** with Python **3.11+**. For knowledge browsing and
retrieval, also install Node.js **22.22.0+** and npm. Run the server as the account
whose Codex sessions you want to use, with that account’s existing Codex login.
Set `CODEX_HOME` if its configuration lives outside `~/.codex`.

Install with uv:

```sh
uv tool install agent-host-mcp
```

Or install with pip in your Python environment:

```sh
pip install agent-host-mcp
```

Start the server:

```sh
agent-host-mcp --host 0.0.0.0 --port 7081 --api_key YOUR_MCP_TOKEN
```

Replace `YOUR_MCP_TOKEN` with a long, random secret and use the same value in your
client. This key protects the MCP server; it is **not** an OpenAI API key. Codex
uses its own existing login.

### Use a configuration file instead

Save these values in `config.toml`:

```toml
host = "0.0.0.0"
port = 7081
api_key = "YOUR_MCP_TOKEN"
```

Keep the file private, then start the server:

```sh
chmod 600 config.toml
agent-host-mcp -f config.toml
```

JSON files with the same three fields are also supported. CLI flags override
file settings, so you can change the port without editing the file:

```sh
agent-host-mcp -f config.toml --port 7082
```

`--api-key` is an alias for `--api_key`; `--config` is an alias for `-f`.
Without explicit settings, the host is `127.0.0.1` and the port is `7081`.
If no API key is supplied by flag or file, the server uses `MCP_TOKEN` from the
environment, then `.env` in its working directory.

The pinned OpenWiki dependency is installed automatically on first knowledge
access and reused afterward. That first request needs npm registry access and
may take longer; no extra setup command is required.

### 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:

```bash
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:

```sh
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:

```json
{"string":"6 * 7"}
```

Then call `execute` again with the returned ID:

```json
{"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](REFERENCE.md)
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.

Credential precedence is CLI `--api_key`, configuration `api_key`, exported
`MCP_TOKEN`, then `.env`. Restart the server after changing its settings.

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](REFERENCE.md#long-running-tool-actions-and-sse).
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

Check the installed version:

```sh
agent-host-mcp --version
```

Open the host’s `/` page, or ask your connected assistant to call `list_models`
and `list_sessions`. These discovery tools do not submit model turns or delete
sessions. Open `/knowledge` to sign in and browse saved knowledge.

| 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 | Check Node.js/npm, npm registry access on first use, 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](REFERENCE.md).
