Connect local MCP to Codex

MaskPilot MCP listens only on the local machine. Codex connects to the client over local HTTP and can call tools within the permissions of the currently signed-in account.

Requirements

Before connecting, confirm that:

1. The MaskPilot client is running and signed in.
2. MCP is enabled in the client settings.
3. Codex and MaskPilot are on the same computer.
4. The account has permission to use the required MCP tools and resources.

The default MCP endpoint is:

http://127.0.0.1:38427/mcp

The health endpoint is:

http://127.0.0.1:38427/health

Configure the access token

Copy the MCP token from MaskPilot and provide it through an environment variable. For the current PowerShell session:

$env:MASKPILOT_MCP_TOKEN = "your-token"

Treat this token as local automation access. Do not commit it to a repository or expose it in screenshots and public logs.

Add the Codex configuration

Add the following MCP server configuration to Codex:

[mcp_servers.maskpilot]
url = "http://127.0.0.1:38427/mcp"
bearer_token_env_var = "MASKPILOT_MCP_TOKEN"

Save the configuration and reload the MCP connection in Codex.

Verify the connection

Confirm that the health endpoint responds, then ask Codex to list the tools exposed by MaskPilot. Start with a read-only operation, such as listing resources visible to the current account.

If a tool call is denied, review the signed-in account’s permissions and access to the target resource instead of exposing the token more broadly.

Common errors

Message	Check first
Connection failed	Client status, MCP setting, and whether the port is already in use
Invalid token	The environment variable matches the current client token
Method not found	Client and caller use compatible MCP protocol behavior
Unknown tool	The tool name comes from the currently returned tool list