Terminal agents
Connect Claude Code and Codex to CODEXIS AI over HTTP or local stdio.
To connect, you need your API key and the MCP server URL https://vm.codexis.ai/mcp. The key determines the CODEXIS AI account and whose credits are used.
Configure Codex in a file
Configure Codex for local work through ~/.codex/config.toml on the machine where it runs. Add this section to your existing file and replace the example key. Keep the file containing your key out of Git.
[mcp_servers.codexis]
url = "https://vm.codexis.ai/mcp"
http_headers = { "X-Api-Key" = "api-VAS_KLIC" }If you supply the key through an environment variable, replace the http_headers line with the following setting. The value on the right is the variable’s name; it must be available to the Codex or desktop application process at startup. Exporting it in a separate terminal does not update an already running desktop application.
env_http_headers = { "X-Api-Key" = "CODEXIS_AGENT_API_KEY" }Start a new session and check that the server is registered. In the conversation, /mcp shows connection status and available tools.
codex mcp listThis setup authenticates with an API key. The codex mcp login command is for OAuth servers. See the official OpenAI documentation for the configuration format.
Claude Code
Add .mcp.json to your project root, or merge the codexis entry into your existing server configuration. Set CODEXIS_AGENT_API_KEY in the environment that launches Claude Code.
{
"mcpServers": {
"codexis": {
"type": "http",
"url": "https://vm.codexis.ai/mcp",
"headers": {
"X-Api-Key": "${CODEXIS_AGENT_API_KEY}"
}
}
}
}After starting Claude Code, approve use of the project’s MCP server. Use /mcp to check the connection and tools. You can also list the configuration from the terminal.
claude mcp listThe Claude Code documentation covers project configuration and reading headers from environment variables.
Local stdio for Codex and Claude Code
Use stdio to run the MCP process locally, for example to attach files from an allowed local folder. Prepare the CLI and sign in to its profile. The following command reads the key through a hidden prompt.
codexis-agent-cli auth login --endpoint https://vm.codexis.aiIn Codex, use this configuration instead of the HTTP section. The executable must be available in the client’s environment; for desktop use, you can specify its full path.
[mcp_servers.codexis]
command = "codexis-agent-cli"
args = ["mcp", "serve"]In Claude Code, the equivalent .mcp.json entry is as follows.
{
"mcpServers": {
"codexis": {
"type": "stdio",
"command": "codexis-agent-cli",
"args": ["mcp", "serve"]
}
}
}The MCP process uses the stored profile of the user running it. Add --read-only and --allow-path to args as described in the MCP guide. When running as another user, prepare the profile in that user’s environment.
Check the connection and run a first task
First ask the client to check the connected account using identity_get and list projects using project_list. Then ask it to create a project, start a chat or send a message. The message_watch tool observes a specific answer; how progress updates appear depends on the client.
For HTTP 401, check the key and whether it is sent in X-Api-Key. For connection errors, check that the complete MCP URL is reachable from where the client makes its requests. If tools are missing, check that the connector is enabled for the session and allowed by your organization.
Next steps
Attachments, progress and controls through MCP · CLI · REST API v2