Skip to content
GuidesAlso known as: agent credentials, judge key, MCP authentication, upload token, M3_ACCESS_TOKEN

Configure credentials ​

Credentials enter M3 under a source name and reach a child process under the name that process expects. In the mapping OPENAI_API_KEY=MY_OPENAI_KEY, M3 reads MY_OPENAI_KEY and sets OPENAI_API_KEY for the agent.

Credential destinations ​

ProcessDestinationHow to configure it
stdio MCP serverA variable the server expects, such as DEMO_SERVICE_TOKENMap the source value into the server's configured environment. The value goes to the server, not the agent calling its tools.
HTTP MCP serverAn authorization header or bearer token accepted by the endpointConfigure authentication on the HTTP server connection. Configure the agent's model-provider key on its harness.
Native agent harnessA provider variable, such as OPENAI_API_KEYSet credential_env on the kit.agents(...) selection. Each native adapter isolates its child environment. An explicit credential_env replaces the harness's default credential variables; credential_env={} forwards none. Codex may reuse eligible host authentication when no credential is forwarded; Pi, Claude Code, and OpenCode do not copy host login files into their temporary homes.
ACP agentA variable the ACP process expectsAdd an exact ${SOURCE_NAME} reference to the ACP manifest's env mapping. M3 starts ACP with an isolated environment containing its configured entries.
LLM judgeM3_JUDGE_API_KEY by default, or the key variable configured for a custom endpointSet the key in the M3 process environment or map a source with the judge: scope. A judge does not borrow an agent key.
M3 run uploadSaved CLI credential or M3_ACCESS_TOKENFor local uploads, run m3 auth login, then start tests with m3 test --upload. For CI, create an access token on your organization's Access tokens page in the M3 account console and store it as M3_ACCESS_TOKEN in the CI secret store. See Manage M3 access.

M3_ACCESS_TOKEN authenticates M3 uploads. m3 test and m3 ci test remove it from the pytest child environment, and M3 rejects that exact variable name in agent and judge mappings or ACP manifests. Agent providers and judges need their own credentials.

Credential sources ​

The SDK reads the process environment and does not load dotenv files. The CLI also reads the process environment and automatically loads .env from the project root (--project-root, or the nearest m3.toml at or above the current directory, stopping at the Git root, otherwise the current directory) when that file exists. Pass --env-file PATH to load a custom file instead.

When an environment file is loaded, values already present in the process environment take precedence, including empty values. File values fill names absent from the process environment. Values in the file are not interpolated. If an ambient variable is set but empty, M3 will not replace it with the non-empty value from the file.

For local uploads, m3 auth login uses device authorization in the M3 account console and saves a 60-day CLI credential in a supported operating-system credential store. An environment-provided M3_ACCESS_TOKEN always takes precedence. If CI, GITHUB_ACTIONS, or GITLAB_CI has a non-empty value, M3 requires M3_ACCESS_TOKEN and never reads the interactive credential store. Without one of those markers, commands can use the saved CLI credential when M3_ACCESS_TOKEN is absent, including m3 ci test. A selected --env-file can provide values to CLI test commands. Do not commit files containing live credentials.

Common configuration mistakes ​

  • In TARGET=SOURCE, the child reads the target name and M3 reads the source name from its environment.
  • M3 loads .env only from the project root, not from parent directories or the test directory. Pass --env-file PATH for a file elsewhere, or export the values into the process environment.
  • An empty ambient variable still overrides a non-empty value from the environment file.
  • Configure a key on the process that uses it: the MCP server, agent harness, or judge.
  • Host login behavior differs between native harnesses. Use an explicit mapping when an isolated child process needs a provider key.
  • M3_ACCESS_TOKEN cannot replace a model-provider or judge credential. Give each one its own source variable and credential.

Next steps ​