SDK-based MCP server that brings Akeyless Agentic Runtime Authority (ARA) to OpenAI Codex — without installing the Akeyless CLI.
This package exposes only the ARA MCP tools (list-secrets, query-db, service-execute, list-sub-tools), matching akeyless mcp-runtime-authority. It does not include static-secret or environment-variable tools.
Codex orchestrates. Akeyless holds the credentials. Secret values never enter the model context.
npm install -g @akeyless-community/codex-mcpOr run without installing:
npx -y @akeyless-community/codex-mcpSet credentials in the MCP server process environment (not in Codex prompts):
export AKEYLESS_ACCESS_ID="p-xxxxx"
export AKEYLESS_ACCESS_KEY="your-access-key"
export AKEYLESS_GATEWAY_URL="https://your-gateway.example.com:8000"
export AKEYLESS_AGENT_ID="codex-agent"AKEYLESS_GATEWAY_URL is the only gateway setting required. The SDK API base (/api/v2) and ARA execution base are derived automatically — same pattern as the Claude connector.
See .env.example for JWT, Universal Identity, cloud IAM, and token auth.
Add to ~/.codex/config.toml:
[mcp_servers.akeyless-ara]
command = "npx"
args = ["-y", "@akeyless-community/codex-mcp"]
enabled = true
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 120
[mcp_servers.akeyless-ara.env]
AKEYLESS_ACCESS_ID = "p-xxxxx"
AKEYLESS_ACCESS_KEY = "your-access-key"
AKEYLESS_GATEWAY_URL = "https://your-gateway.example.com:8000"
AKEYLESS_AGENT_ID = "codex-agent"
[mcp_servers.akeyless-ara.tools.query-db]
approval_mode = "prompt"
[mcp_servers.akeyless-ara.tools.service-execute]
approval_mode = "prompt"
[mcp_servers.akeyless-ara.tools.list-secrets]
approval_mode = "auto"Or use the CLI:
codex mcp add akeyless-ara \
--env AKEYLESS_ACCESS_ID=p-xxxxx \
--env AKEYLESS_ACCESS_KEY=your-key \
--env AKEYLESS_GATEWAY_URL=https://your-gateway.example.com:8000 \
-- npx -y @akeyless-community/codex-mcpProject-scoped config: copy examples/.codex/config.toml.
"List my Akeyless ARA secrets."
"Run
SELECT count(*) FROM usersagainst/prod/db/postgres-readonly."
"Use service-execute on
/prod/aws/devopsto list S3 buckets."
| Tool | Purpose |
|---|---|
list-secrets |
List dynamic, rotated, and custom-MCP secrets with ara_allow_access |
query-db |
Run database queries (MySQL, PostgreSQL, MSSQL, Oracle, Snowflake, etc.) |
service-execute |
Run AWS, GCP, Azure, Kubernetes, GitHub, or custom-MCP actions |
list-sub-tools |
(Optional) Discover sub-tools on a service secret before service-execute |
sequenceDiagram
participant Codex as OpenAI Codex
participant MCP as akeyless-codex-ara
participant API as Akeyless API
participant GW as Akeyless Gateway
participant Target as Database / Cloud
Codex->>MCP: list-secrets
MCP->>API: list-items (ara-only: true)
API-->>MCP: secret paths + target types
MCP-->>Codex: metadata only
Codex->>MCP: query-db / service-execute
MCP->>GW: /config/target_query
GW->>Target: action with JIT credentials
Target-->>GW: results
GW-->>MCP: JSON results
MCP-->>Codex: results (no credentials)
- Akeyless Gateway with Runtime Authority and AI Insights configured
- ARA role rules with Allow Access on secret paths
- Dynamic secrets with Agentic Runtime Authority enabled in the Console
When list-secrets returns zero results, check the diagnostics.troubleshooting hints in the response.
codex plugin marketplace add akeyless-community/codex-akeyless-mcpThen in Codex: /plugins → Akeyless Community → install Akeyless ARA.
See Marketplace guide.
- Secretless by design — list tools return metadata only; execute tools use credentials server-side via the Gateway
- Codex approval — set
promptorapproveforquery-dbandservice-execute - Least privilege — scope RBAC to ARA-enabled secret paths only
- Single gateway URL — point
AKEYLESS_GATEWAY_URLat your organization's gateway
See SECURITY.md.
cd codex-akeyless-integration
npm install
npm test
npm run build
npm start- claude-akeyless-connector — same ARA surface for Claude Desktop
- Akeyless ARA docs
Apache-2.0