{"_id":"@amaretto-software-labs/ai-admin-api-mcp","name":"@amaretto-software-labs/ai-admin-api-mcp","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@amaretto-software-labs/ai-admin-api-mcp","version":"0.0.1","private":false,"license":"MIT","type":"module","packageManager":"pnpm@10.29.1","repository":{"type":"git","url":"git+https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp.git"},"bugs":{"url":"https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp/issues"},"homepage":"https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp#readme","bin":{"ai-admin-api-mcp":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","check":"tsc -p tsconfig.json --noEmit","test":"vitest run","test:watch":"vitest","test:live:openai":"vitest run src/providers/openai/live.test.ts","test:live:anthropic":"vitest run src/providers/anthropic/live.test.ts","test:live:google-billing":"echo \"Google Cloud Billing provider is planned; see docs/google-cloud-billing.md\"","start:stdio":"tsx src/cli.ts --stdio","start:http":"tsx src/cli.ts --http --port 8787","start:https":"tsx src/cli.ts --https --port 8787"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^24.0.0","tsx":"^4.20.0","typescript":"^5.8.0","vitest":"^3.2.0"},"gitHead":"9ba4662e6145c818a9f0140b7b6357431b629825","_id":"@amaretto-software-labs/ai-admin-api-mcp@0.0.1","description":"Read-only MCP server for querying AI provider administration APIs and returning normalized usage, cost, and dashboard data.","_nodeVersion":"23.10.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-aTn/R+C3WjByjspaUbcoAxG+0NwCHE5SI/zO7PcooEePAYbBRPo9F4CURw8LO4KqX/PXhl/XP3ztnl+XePksdg==","shasum":"202a7dee751321b7b69b1a5d6e73ad20eeb72c07","tarball":"https://registry.npmjs.org/@amaretto-software-labs/ai-admin-api-mcp/-/ai-admin-api-mcp-0.0.1.tgz","fileCount":127,"unpackedSize":268035,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDNRgp/Eha1P3P5HZ3k5pBqsW6uYcwgeAgN+x0yA6BFLAiAFPRtVx256EReyN7RRB8nMl5Eg7bzFHkCp/RGabCsu1A=="}]},"_npmUser":{"name":"vlad_vasoftware","email":"vlad@vasoftware.co.uk"},"directories":{},"maintainers":[{"name":"vlad_vasoftware","email":"vlad@vasoftware.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-admin-api-mcp_0.0.1_1781461584059_0.5669791772460497"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-14T18:26:23.885Z","0.0.1":"2026-06-14T18:26:24.206Z","modified":"2026-06-14T18:26:24.489Z"},"maintainers":[{"name":"vlad_vasoftware","email":"vlad@vasoftware.co.uk"}],"description":"Read-only MCP server for querying AI provider administration APIs and returning normalized usage, cost, and dashboard data.","homepage":"https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp#readme","repository":{"type":"git","url":"git+https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp.git"},"bugs":{"url":"https://github.com/Amaretto-Software-Labs/ai-admin-api-mcp/issues"},"license":"MIT","readme":"# AI Admin API MCP Server\n\nRead-only MCP server for querying AI provider administration APIs and returning normalized usage, cost, and dashboard data.\n\n## Status\n\nImplemented providers:\n\n- OpenAI Admin API usage, costs, projects, users, and project API keys.\n- Anthropic Admin API organization metadata, workspaces, API keys, messages usage, and costs.\n\nPlanned providers:\n\n- Google Cloud Billing export through BigQuery. This provider is not implemented yet. When it ships, release notes must state that direct BigQuery billing export queries can incur Google Cloud query costs.\n\nAll MCP tools are read-only. The server does not expose provider mutation tools.\n\n## Tech Stack\n\n- Node.js 22+\n- TypeScript\n- pnpm\n- `@modelcontextprotocol/sdk`\n- Zod input schemas\n- Vitest\n\n## Quick Start\n\n```sh\npnpm install\npnpm check\npnpm test\n```\n\nRun over STDIO:\n\n```sh\nOPENAI_ADMIN_KEY=sk-admin-... \\\nANTHROPIC_ADMIN_KEY=sk-ant-admin-... \\\npnpm start:stdio\n```\n\nRun over Streamable HTTP:\n\n```sh\nOPENAI_ADMIN_KEY=sk-admin-... \\\nANTHROPIC_ADMIN_KEY=sk-ant-admin-... \\\nMCP_HTTP_AUTH_TOKEN=local-proxy-token \\\npnpm start:http\n```\n\nHTTP listens on `http://127.0.0.1:8787/mcp`. Pass `--unsafe-local-http` only for local development where another process already protects the endpoint.\n\nRun the gateway-compatible local HTTPS endpoint with a local development certificate:\n\n```sh\nOPENAI_ADMIN_KEY=sk-admin-... \\\nANTHROPIC_ADMIN_KEY=sk-ant-admin-... \\\nMCP_HTTP_AUTH_TOKEN=local-proxy-token \\\nMCP_HTTPS_CERT_PATH=/path/to/localhost.pem \\\nMCP_HTTPS_KEY_PATH=/path/to/localhost.key \\\npnpm start:https\n```\n\nHTTPS listens on `https://127.0.0.1:8787/mcp`.\n\n## Configuration\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `AI_ADMIN_ENABLED_PROVIDERS` | No | Comma-separated `openai,anthropic`. Defaults to providers with static credentials present. |\n| `AI_ADMIN_REQUIRED_PROVIDERS` | No | Comma-separated providers that must be enabled and statically configured at startup. |\n| `AI_ADMIN_CREDENTIAL_MODE` | No | Only `static` is implemented in this runtime build. `pass_through` and `hybrid` are documented gateway contracts and fail fast. |\n| `OPENAI_ADMIN_KEY` | OpenAI static mode | OpenAI Admin API key. |\n| `OPENAI_BASE_URL` | No | Override for tests or compatible OpenAI Admin API gateways. Defaults to `https://api.openai.com/v1`. |\n| `ANTHROPIC_ADMIN_KEY` | Anthropic static mode | Anthropic Admin API key, sent as `x-api-key`. |\n| `ANTHROPIC_OAUTH_TOKEN` | Anthropic static mode | Optional Anthropic OAuth bearer token with admin scope. |\n| `ANTHROPIC_BASE_URL` | No | Override for tests or compatible Anthropic Admin API gateways. Defaults to `https://api.anthropic.com/v1`. |\n| `ANTHROPIC_VERSION` | No | Anthropic API version. Defaults to `2023-06-01`. |\n| `ANTHROPIC_BETA` | No | Comma-separated Anthropic beta headers, for example `fast-mode-2026-02-01`. |\n| `MCP_HTTP_AUTH_TOKEN` | HTTP mode | Bearer token required by the MCP HTTP endpoint unless unsafe local mode is used. |\n| `MCP_HTTPS_CERT_PATH` | HTTPS mode | PEM certificate path for local HTTPS. |\n| `MCP_HTTPS_KEY_PATH` | HTTPS mode | PEM private-key path for local HTTPS. |\n| `MCP_CACHE_TTL_SECONDS` | No | Dashboard bundle cache TTL in seconds. Metadata list tools cache for 300 seconds. Defaults to `60`. |\n| `MCP_USER_AGENT` | No | Optional user agent context for future outbound request metadata. |\n\n## Credentials\n\nProvider credentials must come from environment variables or an external host secret integration. They must never be sent as normal MCP tool arguments.\n\nIn v0.1 static mode, these credential refs are accepted:\n\n- `credential:openai:static`\n- `credential:anthropic:static`\n\nOmit `credential_ref` to use the static provider credential. Unknown refs are rejected.\n\nPass-through and broker modes are deployment contracts for an operator-supplied gateway. The gateway, credential store, tenant policy, audit layer, and envelope signing are outside this runtime build. See [pass-through gateway docs](docs/pass-through-gateway.md).\n\n## Tools\n\nCommon tools:\n\n- `ai_admin_list_providers`\n- `ai_admin_query_usage`\n- `ai_admin_query_costs`\n- `ai_admin_query_dashboard_bundle`\n\nOpenAI tools:\n\n- `openai_admin_query_usage`\n- `openai_admin_query_costs`\n- `openai_admin_list_projects`\n- `openai_admin_list_users`\n- `openai_admin_list_project_api_keys`\n- `openai_admin_query_dashboard_bundle`\n\nAnthropic tools:\n\n- `anthropic_admin_get_organization`\n- `anthropic_admin_list_workspaces`\n- `anthropic_admin_list_api_keys`\n- `anthropic_admin_query_messages_usage`\n- `anthropic_admin_query_costs`\n- `anthropic_admin_query_dashboard_bundle`\n\n## Resources and Prompts\n\nResources:\n\n- `ai-admin://providers`\n- `ai-admin://providers/{provider}/capabilities`\n- `ai-admin://schema/provider-capability-v1`\n- `ai-admin://schema/usage-fact-v1`\n- `ai-admin://schema/cost-fact-v1`\n- `ai-admin://schema/dashboard-bundle-v1`\n- `openai-admin://capabilities`\n- `anthropic-admin://capabilities`\n\nPrompts:\n\n- `build_usage_dashboard`\n- `investigate_cost_spike`\n- `export_finance_report`\n\n## Provider Notes\n\n- OpenAI usage endpoints have endpoint-specific filters, groupings, and metrics. Unsupported parameters are rejected before any provider call.\n- Anthropic costs are reported in minor units and normalized to USD major units. Priority Tier costs are not included in the Anthropic cost endpoint.\n- Anthropic `speed` usage filters/groupings require `ANTHROPIC_BETA=fast-mode-2026-02-01`.\n- Google Cloud Billing support is planned only. BigQuery queries against billing export tables can be cost-bearing.\n\n## MCP Client Example\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-admin-api\": {\n      \"command\": \"pnpm\",\n      \"args\": [\"--dir\", \"/absolute/path/to/ai-admin-api-mcp\", \"start:stdio\"],\n      \"env\": {\n        \"OPENAI_ADMIN_KEY\": \"sk-admin-...\",\n        \"ANTHROPIC_ADMIN_KEY\": \"sk-ant-admin-...\"\n      }\n    }\n  }\n}\n```\n\n## Docker\n\n```sh\ndocker build -t ai-admin-api-mcp .\ndocker run --rm -p 8787:8787 \\\n  -e OPENAI_ADMIN_KEY \\\n  -e ANTHROPIC_ADMIN_KEY \\\n  -e MCP_HTTP_AUTH_TOKEN \\\n  ai-admin-api-mcp\n```\n\nThe Docker image starts Streamable HTTP mode by default.\n\n## Development\n\n```sh\npnpm check\npnpm test\npnpm test:live:openai\npnpm test:live:anthropic\n```\n\nLive tests are skipped unless provider credentials are present.\n\n## Release\n\nThe **Build and Publish** GitHub Actions workflow runs `pnpm check` and `pnpm test` on pushes and pull requests targeting `main`.\n\nReleases are manual through **Actions -> Build and Publish -> Run workflow** on `main`.\n\nInputs:\n\n- `package-version`: optional SemVer override. If omitted, the workflow uses the committed package version.\n- `npm-tag`: npm dist-tag to use when publishing. Defaults to `latest`.\n- `publish-to-npm`: set to `true` to publish `@amaretto-software-labs/ai-admin-api-mcp` to npm after the release is created.\n\nThe release job aligns the `@amaretto-software-labs/ai-admin-api-mcp` package version in the runner, rebuilds and tests the package, packs one npm tarball, pushes a `v<package-version>` git tag, creates a GitHub Release with the packed artifact, and optionally publishes `@amaretto-software-labs/ai-admin-api-mcp` to npm using trusted publishing. Configure npm trusted publishing for this repository and package before enabling `publish-to-npm`.\n","readmeFilename":"README.md","_rev":"1-48c6e9cd73a157a9f9931cf2c7e3ca0c"}