> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/mcp-tools/account-and-meta.md).

# Account & meta tools

MCP reference for account, identity, API keys, usage and runtime discovery — the get\_contract, get\_me, key-management, run-history and analytics tools.

These tools cover **discovery** (what this Algenta instance is and can execute), **identity and account** (who you are, your limits, your keys), and **history** (simulation runs, analytics, usage). They are read-mostly and the natural first calls an assistant makes before doing real work — `get_contract` tells it what the instance supports, and `get_me` / `get_limits` tell it what the current key is allowed to do.

## Discovery & runtime tools

| Tool                             | What it does                                                                                                                     | Key inputs |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `get_contract`                   | Get the machine-readable platform contract: discovery, query, batch, SQL-report, governed-filter rules, and CLI/MCP entrypoints. | none       |
| `get_runtime_manifest`           | Get the signed runtime manifest: runtime-core inventory, maturity states, proof matrix, and failure contract.                    | none       |
| `get_runtime_modules`            | Get the runtime module proof catalog: shipping modules, proof-matrix entries, maturity counts.                                   | none       |
| `get_runtime_benchmarks`         | Get the runtime benchmark catalog: benchmark classes, SLO budgets, evaluation quality gates.                                     | none       |
| `get_runtime_release_validation` | Get the current runtime release-validation verdict and fail-closed proof status.                                                 | none       |

## Identity & key tools

| Tool                 | What it does                                                       | Key inputs                                                        |
| -------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `get_me`             | Get the current user and organization identity for the active key. | none                                                              |
| `update_me`          | Update the current user name and/or organization name.             | `name`, `org_name`                                                |
| `get_limits`         | Get current plan quotas and limits.                                | none                                                              |
| `list_distributions` | List supported distribution types.                                 | none                                                              |
| `list_templates`     | List built-in simulation templates.                                | none                                                              |
| `list_api_keys`      | List active API keys (never returns raw secrets).                  | none                                                              |
| `create_api_key`     | Create a new key and return its one-time `raw_key`.                | `label` (required), `expires_at` (date-time), `device_limit` (≥0) |
| `revoke_api_key`     | Revoke one key by id.                                              | `key_id` (required)                                               |

## History & usage tools

| Tool            | What it does                                                     | Key inputs                                                                                         |
| --------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `list_runs`     | List recent simulation runs.                                     | `limit` (default `20`, 1–100), `mode` (`auto`/`expert`), `status` (`completed`/`failed`/`running`) |
| `get_run`       | Fetch one simulation run by id.                                  | `run_id` (required)                                                                                |
| `get_analytics` | Get usage analytics: volume, latency p95, outcome distributions. | `days` (default `30`)                                                                              |
| `get_usage`     | Get current billing-period usage vs quota for this key.          | none                                                                                               |

{% hint style="warning" %}
`create_api_key` returns the secret `raw_key` exactly once, in the create response — it is never retrievable again. Store it immediately in a secrets manager. `list_api_keys` returns metadata only.
{% endhint %}

## HTTP mapping

| Tool                             | Method   | Endpoint                       |
| -------------------------------- | -------- | ------------------------------ |
| `get_contract`                   | `GET`    | `/v1/meta/contract`            |
| `get_runtime_manifest`           | `GET`    | `/v1/runtime/manifest`         |
| `get_runtime_modules`            | `GET`    | `/v1/admin/runtime/modules`    |
| `get_runtime_benchmarks`         | `GET`    | `/v1/admin/runtime/benchmarks` |
| `get_runtime_release_validation` | `GET`    | `/v1/admin/runtime/validation` |
| `get_me`                         | `GET`    | `/v1/me`                       |
| `update_me`                      | `PATCH`  | `/v1/me`                       |
| `get_limits`                     | `GET`    | `/v1/limits`                   |
| `list_distributions`             | `GET`    | `/v1/distributions`            |
| `list_templates`                 | `GET`    | `/v1/templates`                |
| `list_api_keys`                  | `GET`    | `/v1/api-keys`                 |
| `create_api_key`                 | `POST`   | `/v1/api-keys`                 |
| `revoke_api_key`                 | `DELETE` | `/v1/api-keys/{key_id}`        |
| `list_runs`                      | `GET`    | `/v1/runs`                     |
| `get_run`                        | `GET`    | `/v1/runs/{run_id}`            |
| `get_analytics`                  | `GET`    | `/v1/runs/analytics`           |
| `get_usage`                      | `GET`    | `/v1/usage`                    |

## Worked examples

### Discover the instance with get\_contract

The contract is the first call an assistant should make: it returns the endpoints, tool entrypoints, and governed-filter rules the instance actually supports.

{% tabs %}
{% tab title="MCP tool call" %}
`get_contract` takes no arguments. It returns a normalized object:

```json
{
  "contract_version": "1.0",
  "brand": "Algenta",
  "api_base_url": "https://api.algenta.ai",
  "mcp_endpoint": "/mcp",
  "mcp_transport": "streamable_http",
  "mcp_protocol_version": "2025-11-25",
  "mcp_tools_endpoint": "/mcp/tools",
  "auth_scheme": "Authorization: Bearer",
  "primary_data_query_contract": { "governed_filter_contract": { "...": "..." } },
  "capability_plane": { "...": "..." },
  "integrations": { "...": "..." }
}
```

{% endtab %}

{% tab title="HTTP" %}

```bash
curl -sS "$ALGENTA_BASE_URL/v1/meta/contract" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"
```

{% endtab %}
{% endtabs %}

### Check identity and remaining quota

{% tabs %}
{% tab title="MCP tool call" %}
`get_me` and `get_usage` take no arguments. `get_usage` reports the current billing period against quota:

```json
{
  "simulations_used": 4210,
  "simulations_limit": 100000,
  "billing_period": "2026-07",
  "plan": "developer",
  "api_calls": 5623,
  "pct_used": 4.21
}
```

{% endtab %}

{% tab title="HTTP" %}

```bash
curl -sS "$ALGENTA_BASE_URL/v1/me" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"
curl -sS "$ALGENTA_BASE_URL/v1/usage" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"
```

{% endtab %}
{% endtabs %}

### Create a scoped API key

{% tabs %}
{% tab title="MCP tool call" %}

```json
{ "label": "ci-pipeline", "device_limit": 2 }
```

```json
{ "id": "$KEY_ID", "label": "ci-pipeline", "raw_key": "de_live_...", "device_limit": 2 }
```

Revoke it later with `revoke_api_key`:

```json
{ "key_id": "$KEY_ID", "revoked": true }
```

{% endtab %}

{% tab title="HTTP" %}

```bash
curl -sS "$ALGENTA_BASE_URL/v1/api-keys" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "ci-pipeline", "device_limit": 2 }'

curl -sS -X DELETE "$ALGENTA_BASE_URL/v1/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"
```

{% endtab %}
{% endtabs %}

## Related references

{% content-ref url="/pages/UvGGKnKB6EqDONoxZRyB" %}
[Authentication & API keys](/getting-started/authentication.md)
{% endcontent-ref %}

{% content-ref url="/pages/7stbYFWr2YSgMNff3QuV" %}
[API overview](/http-api/overview.md)
{% endcontent-ref %}

{% content-ref url="/pages/Jop4vFb3jbV8SWK547JZ" %}
[Control plane tools](/mcp-tools/control-plane.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.algenta.ai/mcp-tools/account-and-meta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.