OpenAI Admin MCP Tools & API Patterns
Overview
The OpenAI Admin MCP server is a read-only view of one OpenAI
organization through the OpenAI Admin API. Every one of its 30 tools is a
GET against the fixed host https://api.openai.com/v1. Nothing in this
plugin can invite, remove, or change a user, create or delete a key, or
change a project or rate limit. If a request needs a change, the answer is
"do it in the OpenAI dashboard", not a tool call.
Connection & Authentication
| Header |
Value |
X-OpenAI-Admin-Key |
An OpenAI Admin key (sk-admin-...) |
In Conduit the connector has one field, Admin Key. Conduit maps it
onto X-OpenAI-Admin-Key; the server then calls OpenAI with
Authorization: Bearer <key>. The key is entered only in the Conduit web
UI (/connect/openai-admin); nothing is set on the client, and Conduit
drops any X-OpenAI-Admin-Key header a client sends.
- An organization owner creates the key at
platform.openai.com/settings/organization/admin-keys.
- A project key (
sk-proj-...) is refused before any request with "This
is not an OpenAI Admin key". So is anything that does not start with
sk-.
- OpenAI has no read-only Admin key. The key Conduit holds could invite or
remove users and delete keys in the OpenAI dashboard or API, even though
this server only reads. Use a dedicated Admin key for Conduit so it can
be revoked on its own.
- No
OpenAI-Organization header is sent. The organization is whichever
one the Admin key belongs to. One connection reaches exactly one
OpenAI organization. A client with its own OpenAI organization needs
its own Admin key; a client that is a project inside the MSP's
organization is reviewed through that organization's key.
Tool Surface and Conduit Gating
Tool names follow openai_admin_<area>_<action>: collections end in
_list, single objects in _get, project-scoped tools start with
project_.
| Area |
Tools |
| Seats |
openai_admin_users_list, openai_admin_user_get, openai_admin_invites_list, openai_admin_invite_get |
| Projects |
openai_admin_projects_list, openai_admin_project_get, openai_admin_project_users_list, openai_admin_project_user_get, openai_admin_project_service_accounts_list, openai_admin_project_service_account_get, openai_admin_project_rate_limits_list |
| Keys (admin-gated) |
openai_admin_project_api_keys_list, openai_admin_project_api_key_get, openai_admin_admin_api_keys_list, openai_admin_admin_api_key_get |
| Audit (admin-gated) |
openai_admin_audit_logs_list |
| Certificates |
openai_admin_certificates_list, openai_admin_certificate_get, openai_admin_project_certificates_list |
| Usage |
openai_admin_usage_completions, openai_admin_usage_embeddings, openai_admin_usage_moderations, openai_admin_usage_images, openai_admin_usage_audio_speeches, openai_admin_usage_audio_transcriptions, openai_admin_usage_vector_stores, openai_admin_usage_code_interpreter_sessions, openai_admin_usage_file_search_calls, openai_admin_usage_web_search_calls |
| Cost |
openai_admin_costs |
Admin-gated in Conduit. The four key-inventory tools and
openai_admin_audit_logs_list are read-only, but Conduit classifies them
as sensitive and requires the admin tier to call them. A user or agent
granted only read on OpenAI Admin can call the other 25 tools and gets a
denial on these five. Confirm the live grant in the Conduit access editor
before planning a workflow around them, and say so in the output when a
step was skipped for this reason rather than reporting "no keys found".
Pagination
Two styles. The server never pages automatically, so check for more
before calling a result complete.
List tools (users, invites, projects, project members, service
accounts, keys, rate limits, certificates, audit log):
- Take
after (and before on the audit log and rate limits) plus
limit (1-100, default 20; larger values are capped).
- Return
data, first_id, last_id, and has_more unchanged.
- Next page: call again with
after set to the previous last_id while
has_more is true.
Usage and cost tools:
start_time is required; end_time is optional and exclusive. Both are
Unix seconds (integers), e.g. 1730419200 for 2024-11-01T00:00:00Z.
limit counts time buckets, not rows. For usage it depends on
bucket_width: 1d default 7 / max 31, 1h default 24 / max 168, 1m
default 60 / max 1440. openai_admin_costs is daily only, default 7,
max 180.
- Next page: pass the previous response's
next_page as page while
has_more is true.
A month of daily usage fits in one call with bucket_width: "1d" and
limit: 31. A month of daily cost fits with limit: 31.
Truncated Pages
Tool output is capped (about 60,000 characters by default). When a page
is too large, the server drops items from the end of data and says
truncated: true, returned_items, and total_items_in_page. The
cursors (last_id, next_page) still describe the full page, so
paging on from them would silently skip the dropped items. Repeat the
same request with a smaller limit instead. Grouped usage queries over
long ranges are the usual cause.
Error Handling
Every non-2xx answer is a tool error carrying the HTTP status, OpenAI's
error type and message, param/code when present, and a request_id
to quote in an OpenAI support ticket.
| Status |
Meaning |
Action |
| 401 / 403 |
The key is invalid, revoked, not an Admin key, or lacks permission for this endpoint |
Ask the org owner to check the Admin key; reconnect in Conduit with a new one |
| 404 |
Unknown user, project, key, invite, or certificate ID |
Re-list to get a current ID |
| 429 |
Rate limited by OpenAI |
Wait the Retry after Ns the error states, then retry once; do not fan out parallel calls |
| Conduit denial |
Tool is admin-gated and the caller has read |
Report the gap; a Conduit admin grants admin if appropriate |
Argument problems (an enum value the endpoint does not accept, a
non-integer time, a malformed ID) are rejected before any request is
sent, with a message naming the parameter.
Gotchas
- Grouping fields are null unless you group by them. A usage or cost
row only carries
project_id, user_id, api_key_id, or model when
that field is in group_by. Ungrouped results cannot be attributed to a
client project.
- Times are UTC Unix seconds. Compute month boundaries in UTC; a
local-midnight boundary shifts a day of spend between months.
- The Conduit key shows up in the inventory. The Admin key you
connected appears in
openai_admin_admin_api_keys_list with a recent
last_used_at. Identify it before flagging "unknown Admin keys".
- Secrets are never returned. Key tools return names, owners, dates,
and a redacted hint only.
- The audit log must be enabled for the organization. If
openai_admin_audit_logs_list errors, or returns nothing over a period
where you know keys or members changed, report "audit logging is off or
unavailable" as a finding, not "no events".
Related Skills
1---2name: openai-admin-api-patterns3description: >4 OpenAI Admin MCP fundamentals: the Admin key sent as the5 `X-OpenAI-Admin-Key` header through Conduit, the 30-tool read-only6 surface and which five tools Conduit admin-gates, the two pagination7 styles (object cursors for lists, page tokens for usage and cost8 reports), Unix-second time ranges, truncated pages, and the error and9 429 shapes the server returns.10when_to_use: >-11 When connecting to or calling OpenAI Admin through Conduit, paging12 through results, or diagnosing a failed OpenAI Admin tool call. Use13 when: openai admin api, openai admin key, X-OpenAI-Admin-Key, openai14 admin pagination, openai admin 401, openai admin 403, openai admin 429,15 truncated openai page, or openai admin tools.16metadata:17 source: https://skillmd.com/skills/wyre-ai/openai-admin-api-patterns18---1920# OpenAI Admin MCP Tools & API Patterns2122## Overview2324The OpenAI Admin MCP server is a read-only view of one OpenAI25organization through the OpenAI Admin API. Every one of its 30 tools is a26GET against the fixed host `https://api.openai.com/v1`. Nothing in this27plugin can invite, remove, or change a user, create or delete a key, or28change a project or rate limit. If a request needs a change, the answer is29"do it in the OpenAI dashboard", not a tool call.3031## Connection & Authentication3233| Header | Value |34|--------|-------|35| `X-OpenAI-Admin-Key` | An OpenAI **Admin** key (`sk-admin-...`) |3637In Conduit the connector has one field, **Admin Key**. Conduit maps it38onto `X-OpenAI-Admin-Key`; the server then calls OpenAI with39`Authorization: Bearer <key>`. The key is entered only in the Conduit web40UI (`/connect/openai-admin`); nothing is set on the client, and Conduit41drops any `X-OpenAI-Admin-Key` header a client sends.4243- An organization owner creates the key at44 platform.openai.com/settings/organization/admin-keys.45- A project key (`sk-proj-...`) is refused before any request with "This46 is not an OpenAI Admin key". So is anything that does not start with47 `sk-`.48- OpenAI has no read-only Admin key. The key Conduit holds could invite or49 remove users and delete keys in the OpenAI dashboard or API, even though50 this server only reads. Use a dedicated Admin key for Conduit so it can51 be revoked on its own.52- No `OpenAI-Organization` header is sent. The organization is whichever53 one the Admin key belongs to. **One connection reaches exactly one54 OpenAI organization.** A client with its own OpenAI organization needs55 its own Admin key; a client that is a project inside the MSP's56 organization is reviewed through that organization's key.5758## Tool Surface and Conduit Gating5960Tool names follow `openai_admin_<area>_<action>`: collections end in61`_list`, single objects in `_get`, project-scoped tools start with62`project_`.6364| Area | Tools |65|------|-------|66| Seats | `openai_admin_users_list`, `openai_admin_user_get`, `openai_admin_invites_list`, `openai_admin_invite_get` |67| Projects | `openai_admin_projects_list`, `openai_admin_project_get`, `openai_admin_project_users_list`, `openai_admin_project_user_get`, `openai_admin_project_service_accounts_list`, `openai_admin_project_service_account_get`, `openai_admin_project_rate_limits_list` |68| Keys (admin-gated) | `openai_admin_project_api_keys_list`, `openai_admin_project_api_key_get`, `openai_admin_admin_api_keys_list`, `openai_admin_admin_api_key_get` |69| Audit (admin-gated) | `openai_admin_audit_logs_list` |70| Certificates | `openai_admin_certificates_list`, `openai_admin_certificate_get`, `openai_admin_project_certificates_list` |71| Usage | `openai_admin_usage_completions`, `openai_admin_usage_embeddings`, `openai_admin_usage_moderations`, `openai_admin_usage_images`, `openai_admin_usage_audio_speeches`, `openai_admin_usage_audio_transcriptions`, `openai_admin_usage_vector_stores`, `openai_admin_usage_code_interpreter_sessions`, `openai_admin_usage_file_search_calls`, `openai_admin_usage_web_search_calls` |72| Cost | `openai_admin_costs` |7374**Admin-gated in Conduit.** The four key-inventory tools and75`openai_admin_audit_logs_list` are read-only, but Conduit classifies them76as sensitive and requires the `admin` tier to call them. A user or agent77granted only `read` on OpenAI Admin can call the other 25 tools and gets a78denial on these five. Confirm the live grant in the Conduit access editor79before planning a workflow around them, and say so in the output when a80step was skipped for this reason rather than reporting "no keys found".8182## Pagination8384Two styles. The server never pages automatically, so check for more85before calling a result complete.8687**List tools** (users, invites, projects, project members, service88accounts, keys, rate limits, certificates, audit log):8990- Take `after` (and `before` on the audit log and rate limits) plus91 `limit` (1-100, default 20; larger values are capped).92- Return `data`, `first_id`, `last_id`, and `has_more` unchanged.93- Next page: call again with `after` set to the previous `last_id` while94 `has_more` is true.9596**Usage and cost tools**:9798- `start_time` is required; `end_time` is optional and exclusive. Both are99 Unix seconds (integers), e.g. `1730419200` for 2024-11-01T00:00:00Z.100- `limit` counts **time buckets**, not rows. For usage it depends on101 `bucket_width`: `1d` default 7 / max 31, `1h` default 24 / max 168, `1m`102 default 60 / max 1440. `openai_admin_costs` is daily only, default 7,103 max 180.104- Next page: pass the previous response's `next_page` as `page` while105 `has_more` is true.106107A month of daily usage fits in one call with `bucket_width: "1d"` and108`limit: 31`. A month of daily cost fits with `limit: 31`.109110## Truncated Pages111112Tool output is capped (about 60,000 characters by default). When a page113is too large, the server drops items from the end of `data` and says114`truncated: true`, `returned_items`, and `total_items_in_page`. The115cursors (`last_id`, `next_page`) still describe the **full** page, so116paging on from them would silently skip the dropped items. Repeat the117same request with a smaller `limit` instead. Grouped usage queries over118long ranges are the usual cause.119120## Error Handling121122Every non-2xx answer is a tool error carrying the HTTP status, OpenAI's123error type and message, `param`/`code` when present, and a `request_id`124to quote in an OpenAI support ticket.125126| Status | Meaning | Action |127|--------|---------|--------|128| 401 / 403 | The key is invalid, revoked, not an Admin key, or lacks permission for this endpoint | Ask the org owner to check the Admin key; reconnect in Conduit with a new one |129| 404 | Unknown user, project, key, invite, or certificate ID | Re-list to get a current ID |130| 429 | Rate limited by OpenAI | Wait the `Retry after Ns` the error states, then retry once; do not fan out parallel calls |131| Conduit denial | Tool is admin-gated and the caller has `read` | Report the gap; a Conduit admin grants `admin` if appropriate |132133Argument problems (an enum value the endpoint does not accept, a134non-integer time, a malformed ID) are rejected before any request is135sent, with a message naming the parameter.136137## Gotchas138139- **Grouping fields are null unless you group by them.** A usage or cost140 row only carries `project_id`, `user_id`, `api_key_id`, or `model` when141 that field is in `group_by`. Ungrouped results cannot be attributed to a142 client project.143- **Times are UTC Unix seconds.** Compute month boundaries in UTC; a144 local-midnight boundary shifts a day of spend between months.145- **The Conduit key shows up in the inventory.** The Admin key you146 connected appears in `openai_admin_admin_api_keys_list` with a recent147 `last_used_at`. Identify it before flagging "unknown Admin keys".148- **Secrets are never returned.** Key tools return names, owners, dates,149 and a redacted hint only.150- **The audit log must be enabled** for the organization. If151 `openai_admin_audit_logs_list` errors, or returns nothing over a period152 where you know keys or members changed, report "audit logging is off or153 unavailable" as a finding, not "no events".154155## Related Skills156157- [seat-key-inventory](../seat-key-inventory/SKILL.md) - who has access and which keys exist158- [spend-review](../spend-review/SKILL.md) - usage, cost, and chargeback by project159- [security-review](../security-review/SKILL.md) - audit log, orphaned keys, certificates