ai-credits-mcp

MCP server that exposes AI credit usage data from OpenMeter to the TAIS AI chat service. Queries are automatically scoped to the calling tenant and restricted to admin users.

Tools

All tools require the caller to be in the Administrators group. Each tool returns a markdown table (for the LLM to summarise) and a [Download Excel](url) link pointing to a temporary .xlsx file served at /download/<token>. The link expires after 10 minutes. They are automatically scoped to the calling user's tenant — no tenant parameter is exposed.

If the request exceeds 50 rows in the text preview, the table is truncated with a note to see the Excel file for the full dataset.

get_credit_usage_by_tenant

Returns total credits consumed by the tenant as a single aggregated number.

Output columns: tenant, credits

Example prompts:

• "How many AI credits has my tenant used?"

• "What's our total credit spend this month?"

get_credit_usage_summary

Returns credits broken down by user, module, product, and skill — useful for identifying who or what is consuming the most credits.

Output columns: user, module, product, tenant, skill, credits

Example prompts:

• "Show me credit usage broken down by user."

• "Which product or skill is using the most credits?"

• "Give me a credit usage summary for Q1 2026."

get_credit_events

Returns individual raw credit events — the lowest level of detail, one row per event.

Output columns: time, user, module, product, tenant, credits

Example prompts:

• "Show me all credit events from last week."

• "What happened on January 15th in terms of AI usage?"

How the AI decides which tool to call

When you ask about credit usage in the AI chat, the model picks the appropriate tool automatically:

• Totals / "how much overall" → get_credit_usage_by_tenant

• Breakdowns by user / module / skill → get_credit_usage_summary

• Individual events / audit trail → get_credit_events

If no date range is specified, the last 7 days are used by default. To change the range, phrase your question naturally: "...for January 2026" or "...since last month" — the model will translate this to ISO 8601 parameters.

Related MCP server: cloudscope-mcp

Security

The TAIS chatbot-agent-service forwards both headers automatically on every MCP connection.

Running locally

Prerequisites: Python 3.11+, uv

cd ai-credits-mcp
uv sync                        # install dependencies
cp .env.example .env           # add your OPENMETER_API_KEY
uv run main.py
# Server starts at http://localhost:8765

Health check:

curl http://localhost:8765/health
# {"status": "ok"}

AI chat integration

Use the registration script to register the tool and wire it to a TAIS session:

bash scripts/register.sh

The script reads TAIS_JWT from .env, decodes the tenant and user automatically, registers the tool against the local TAIS API, and PATCHes the session. If TAIS_SESSION_ID is not set in .env it will prompt you interactively.

Note: registered tools expire after ~1 hour. Re-run the script when the tool stops responding.

To wire to a session manually:

PATCH http://localhost:5001/api/v2/sessions-service/{sessionId}
Authorization: Bearer <token>
Content-Type: application/json

{"toolIds": ["<tool-id-from-registration>"]}

Environment variables

Project structure

ai-credits-mcp/
├── server.py            # FastMCP server, tools, middleware, download endpoint
├── main.py              # uvicorn entry point
├── scripts/
│   └── register.sh      # registers tool with TAIS and wires it to a session
├── pyproject.toml       # dependencies (mcp, uvicorn, openpyxl, python-dotenv)
└── .env.example         # environment variable template

server.py imports query_credits from the sibling ai-credit-usage/ directory, which handles all OpenMeter API calls.

Aspire registration

Registered in apphost.cs as:

var aiCreditsMcp = builder.AddPythonApp("ai-credits-mcp", "/Users/a.demers/dev/ai-credits-mcp", "main.py")
    .WithUv()
    .WithEnvironment("PYTHONPATH", ".")
    .WithHttpEndpoint(port: 8765, env: "MCP_PORT", isProxied: false)
    .WithHttpHealthCheck("/health")
    .WithEnvironment("OPENMETER_API_KEY", Environment.GetEnvironmentVariable("OPENMETER_API_KEY") ?? "");

Add OPENMETER_API_KEY=<your-key> to the workspace-root .env file.