# Connect OpenAI Codex CLI to SAM.gov data

To connect OpenAI Codex CLI to SAM.gov data, run codex mcp add samgovapi --url https://samgovapi.io/api/mcp --bearer-token-env-var SAMGOVAPI_API_KEY. Codex stores the server in ~/.codex/config.toml, reads the key from that environment variable on every request, and exposes the samgovapi tools in /mcp and to the agent.

Codex reads the bearer token from an environment variable you name, rather than from text in the config, which keeps keys out of dotfiles you might sync. That makes it a good fit for scripted jobs: a supplier screening or a recompete report that Codex writes, runs and keeps in a repository.

- Connects with: MCP
- MCP server: https://samgovapi.io/api/mcp
- REST base: https://samgovapi.io/api/v1
- Auth: Authorization: Bearer <key>, kept in SAMGOVAPI_API_KEY
- Tested: codex-cli 0.167.0: codex mcp add wrote the table above and codex mcp list read it with Bearer token auth (2026-11-13)

## Get a key

Free key at https://samgovapi.io/sign-up, or have the agent call start_signup and approve the link it shows you. Name the variable in bearer_token_env_var. To send other headers from the environment, env_http_headers maps a header name to a variable name.

## Set up OpenAI Codex CLI

1. Export your key: The variable has to be set in the environment Codex starts in.

Shell:

```bash
export SAMGOVAPI_API_KEY="sg_..."
```

2. Add the server: --bearer-token-env-var is only valid for Streamable HTTP servers, which is what this endpoint is.

Terminal:

```bash
codex mcp add samgovapi --url https://samgovapi.io/api/mcp --bearer-token-env-var SAMGOVAPI_API_KEY
```

3. Or edit config.toml: The command writes this table. bearer_token_env_var takes the variable's name, not its value; there is no ${} syntax in Codex config.

~/.codex/config.toml:

```toml
[mcp_servers.samgovapi]
url = "https://samgovapi.io/api/mcp"
bearer_token_env_var = "SAMGOVAPI_API_KEY"
# optional
tool_timeout_sec = 60
```

4. Check it: codex mcp list shows the server with Bearer token auth; /mcp in the TUI lists its tools.

Terminal:

```bash
codex mcp list
```

## Finish account setup once

Data tools unlock after the account answers its onboarding questions: ask the agent to set up your samgovapi account (get_onboarding_questions, then answer_onboarding). Free.

## Check that it works

Ask: "Is UEI ZXBCU6K5KL99 registered in SAM.gov, and when does its registration expire?"

Expected tool call:

```json
{"name":"registration_status","arguments":{"id":"ZXBCU6K5KL99","user_request":"check a registration and its expiry"}}
```

## Things to know

- enabled_tools in the server table limits Codex to a subset, such as registration_status and search_opportunities, if you want a smaller tool list.

## Troubleshooting

- Codex says the token variable is missing: Export SAMGOVAPI_API_KEY before starting codex; a variable set in another terminal is not visible.
- Tool calls time out: Raise tool_timeout_sec. Large award searches with limit=100 can take a few seconds.
- Data tools answer ONBOARDING_REQUIRED: Ask Codex to answer the samgovapi onboarding questions; it calls get_onboarding_questions and answer_onboarding.

## Questions

### Does Codex need OAuth for this server?

No. This server authenticates with a bearer key, so bearer_token_env_var is all it needs.

### Can I use the server in codex exec runs?

Yes. Non-interactive runs load the same config.toml.

## Official documentation

- Codex: Model Context Protocol: https://developers.openai.com/codex/mcp

Checked 2026-11-13. All guides: https://samgovapi.io/agents.md

Independent. Not affiliated with, endorsed by or sponsored by GSA, SAM.gov or any U.S. government agency. Registering in SAM.gov is free at sam.gov.