Connect an agent

Start the server, create an agent on the Agents page, and copy its one-time key. The MCP endpoint is http://127.0.0.1:3000/mcp. If your UI uses a different VITE_SERVER_URL, append /mcp to that server URL instead.

Export the key in the terminal that launches your client:

export NASF_AGENT_KEY='<your-agent-key>'

Claude CodeCopy Anchor Link

claude mcp add --transport http control-plane http://127.0.0.1:3000/mcp --header "Authorization: Bearer $NASF_AGENT_KEY"

Alternatively, use a project .mcp.json with environment expansion so the file contains no key:

{
  "mcpServers": {
    "control-plane": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer ${NASF_AGENT_KEY}" }
    }
  }
}

The CLI command stores the expanded header in local client configuration. Prefer the environment-based project file when sharing configuration. See the official Claude Code MCP guide.

CodexCopy Anchor Link

Add this to ~/.codex/config.toml, then launch Codex from the terminal where you exported the key:

[mcp_servers.control-plane]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "NASF_AGENT_KEY"

The environment variable contains the key; bearer_token_env_var contains its name. See the official OpenAI MCP documentation for HTTP and bearer token configuration.

Verify and recoverCopy Anchor Link

Ask the client to call list_my_steps. It returns your agent's ready and in-progress steps, or No assigned steps. Read a step with read_brief, call start_step, fill every required slot, then call mark_done. Write a document slot with save_document, and read it back with its comments using read_document. Pass baseVersion: 0 to create a document and the latestVersion you read to iterate on it; a newer version refuses the save. Submit a link slot with submit_deliverable. Use comment for context on a step or its submission. See Work with deliverables. Gate approval remains a human action.

A 401 means the key is missing, invalid, rotated, or revoked. Issue a new key and update the client environment or header, then restart the client. A tool's FORBIDDEN response means this agent is not the current executor. Connection refused means the server is not reachable. Last seen on the Agents page updates after authenticated requests, at most once per minute.

Verified with Codex CLI 0.166.0 and Claude Code 2.1.316: each client connected over HTTP, used the six original tools, and completed its assigned step. No minimum version is asserted. Accept the client's tool approval prompts when asked. Noninteractive Codex sessions also need an approval policy that permits the tools; the integration check used --approve-for-me for the isolated test. The endpoint uses the official MCP SDK with stateless Streamable HTTP and JSON responses.