> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CometAPI MCP

> Connect Claude Code, Codex, and other MCP clients to CometAPI to search models, generate text, and create images with one API key.

The CometAPI MCP server connects [Model Context Protocol](https://modelcontextprotocol.io) clients, such as Claude Code and Codex, to CometAPI. CometAPI hosts the server, so there is nothing to install. A connected assistant can search the model catalog, inspect a model, generate text, and create images during a conversation.

The server uses the same API key as the CometAPI API and the [CometAPI CLI](https://apidoc.cometapi.com/developer-tools/cli/overview.md). Authentication is one request header, and no browser sign-in is required.

| Setting | Value |
| - | - |
| URL | `https://mcp.cometapi.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | `Authorization: Bearer <COMETAPI_KEY>` request header |

## Features

* Connect with one URL and your CometAPI API key, with nothing to install
* Search the model catalog that your API key can access, and inspect a model, at no charge
* Generate text with `gpt-6-astra` and create images with `gpt-image-2` at the same price as CometAPI API requests
* Recover a result after a disconnect: read a text receipt or an image task again at no charge
* Control charges: the server sends each generation request one time and does not retry it

## Prerequisites

* A CometAPI API key from the [API keys page](https://www.cometapi.com/console/token). To limit what an assistant can spend, create a dedicated API key for the MCP server: disable **Unlimited Quota** and set a quota.
* An MCP client that supports remote servers over Streamable HTTP with custom request headers, such as Claude Code or Codex

## Connect a client

**1. Set the API key**

To keep the API key out of configuration files, store it in the `COMETAPI_KEY` environment variable. Replace `<COMETAPI_KEY>` with your CometAPI API key:

```bash theme={null}
export COMETAPI_KEY="<COMETAPI_KEY>"
```

**2. Add the server**

> [tab] Claude Code
>
> Create a `.mcp.json` file in the project root, which is the directory where you start Claude Code. If the directory already has a `.mcp.json` file, add the `cometapi` entry to the `mcpServers` object of that file. Use this content:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "cometapi": {
>       "type": "http",
>       "url": "https://mcp.cometapi.com/mcp",
>       "headers": {
>         "Authorization": "Bearer ${COMETAPI_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Claude Code replaces `${COMETAPI_KEY}` with the value of the environment variable, so the file contains no API key. Start Claude Code in the project root from a shell that exports `COMETAPI_KEY`. When Claude Code asks, approve the `cometapi` server.

> [tab] Codex
>
> Add the server with the Codex CLI:
>
> ```bash theme={null}
> codex mcp add cometapi --url https://mcp.cometapi.com/mcp \
>   --bearer-token-env-var COMETAPI_KEY
> ```
>
> `--bearer-token-env-var` takes the name of the environment variable, not the API key itself. Codex stores the name of the environment variable and reads the API key when Codex starts. Start Codex from a shell that exports `COMETAPI_KEY`.

> [tab] Other clients
>
> Add a remote MCP server with the URL, transport, and request header from the table at the top of this page. Store the API key in the secret or environment setting of the client.

**3. Verify the connection**

Check that the client lists the `cometapi` server as connected. In Claude Code and in Codex, the `/mcp` command shows the server status.

Then ask the assistant to search the model catalog. This call is not billed:

```text theme={null}
Use the cometapi search_models tool to find models that match "gpt".
Show five results.
```

The result lists models that your API key can access.

## Try example prompts

To check the accepted parameters before a billed request, use this prompt. The call is not billed:

```text theme={null}
Use the cometapi get_model_schema tool to show the parameters that
gpt-image-2 accepts.
```

To generate text, use this prompt. The request is billed at the same price as a CometAPI API request:

```text theme={null}
Use the cometapi generate_text tool with gpt-6-astra to write a 50-word
product description for a reusable water bottle. Set max_output_tokens to 512.
```

To generate a longer text, use a receipt. A receipt lets the generation run for up to 120 seconds and keeps the result readable until the receipt expires:

```text theme={null}
Use the cometapi prepare_text_generation tool to reserve a receipt. Then call
generate_text with that recovery_id and gpt-6-astra to explain what an API key
is in 100 words. Set max_output_tokens to 512. Read the result with
get_text_result.
```

To create an image, use this prompt. The task is billed when the image is generated:

```text theme={null}
Use the cometapi generate_image tool with gpt-image-2 to create a
minimalist product photo of a stainless steel water bottle on a light
background. Use the low quality and the 1024x1024 size. Read the task with
get_task until the task finishes, then show the task ID.
```

To save the image as a file, use the task ID with the command in the [tool reference](https://apidoc.cometapi.com/developer-tools/mcp/tools.md).

## Tools

| Tool | Purpose | Charge |
| - | - | - |
| `search_models` | Search the model catalog that your API key can access | No charge |
| `get_model_schema` | Inspect one model and its generation parameters | No charge |
| `generate_text` | Generate text with `gpt-6-astra` | Billed |
| `prepare_text_generation` | Reserve a receipt for a text request | No charge |
| `get_text_result` | Read the result of a text request that has a receipt | No charge |
| `generate_image` | Submit an image task for `gpt-image-2` | Billed when the image is generated |
| `get_task` | Read the state and the result of an image task | No charge |

To check progress or to read a result again, use `get_text_result` or `get_task`. These tools are not billed. Do not call `generate_text` or `generate_image` again for that purpose, because a repeated call can start a second billed request.

The client lists `generate_text` and `prepare_text_generation` when your API key can access `gpt-6-astra`. The client lists `generate_image` and `get_task` when your API key can access `gpt-image-2`.

For the parameters, the results, and the errors of each tool, see the [tool reference](https://apidoc.cometapi.com/developer-tools/mcp/tools.md).

## Choose the MCP server, the API, or the CLI

| Use | When |
| - | - |
| MCP server | An assistant in a chat or IDE session needs model search, text, or images during the conversation |
| [CometAPI CLI](https://apidoc.cometapi.com/developer-tools/cli/overview.md) | You work in a terminal or a script, or you need account data such as balance and usage logs |
| [CometAPI API](https://apidoc.cometapi.com/quickstarts/index.md) | You call a model that the MCP tools do not cover, or you build your own integration |

The MCP server and the CLI use the same API key, so you can use both. In the CLI, the commands for usage logs and other account data also require an access token.

## Billing

Catalog searches, model lookups, receipts, and task reads are not billed. `generate_text` and `generate_image` spend your CometAPI balance at the same price as the same request through the CometAPI API. The MCP server adds no fee. For model prices, see the [model directory](https://www.cometapi.com/models/).

The server sends each generation request one time. After a timeout or a disconnect, a request can still complete and be billed. Before you send the request again, check the first request:

| Request | Check |
| - | - |
| Text request with a receipt | Read the receipt with `get_text_result` |
| Text request without a receipt | Check your [usage logs](https://www.cometapi.com/console/log) for a `gpt-6-astra` entry. The entry appears when the generation ends, which can be more than a minute after the request. If the entry exists, the request was billed, and the generated text is not available again. |
| Image task with a task ID | Read the task with `get_task` |
| Image task without a task ID | Check your [usage logs](https://www.cometapi.com/console/log) for a `gpt-image-2` entry. The entry appears when the image is generated, which can take a few minutes. |

To limit what an assistant can spend, use a dedicated API key with a quota. To set a quota or an expiry time through the API, see [Create an API key](https://apidoc.cometapi.com/api/api-keys/create-api-key.md).

## Troubleshooting

> [accordion] The server returns 401 with authentication\_error
>
> Check that `COMETAPI_KEY` is set in the environment that starts the client. Then check that the value is a complete CometAPI API key that is enabled, has not expired, and has remaining quota. To copy the API key, open the [API keys page](https://www.cometapi.com/console/token). The server does not accept account access tokens.

> [accordion] The server returns 403 with authentication\_error
>
> CometAPI denied access for the API key. Requests through the MCP server do not come from your own IP address, so an IP allowlist on the API key blocks these requests. If the API key has an IP allowlist, create a dedicated API key for the MCP server without an IP allowlist, and set a quota on that API key. Otherwise, check the group permissions of the API key.

> [accordion] The client does not list the generation tools
>
> The client lists a generation tool only when your API key can access the model of the tool. To check access, read `gpt-6-astra` or `gpt-image-2` with `get_model_schema`. The client lists the generation tools of a model when the result shows `schemaStatus` as `verified`.

## Links

* [Tool reference](https://apidoc.cometapi.com/developer-tools/mcp/tools.md)
* [CometAPI CLI](https://apidoc.cometapi.com/developer-tools/cli/overview.md)
* [Model API quickstarts](https://apidoc.cometapi.com/quickstarts/index.md)
* [Model directory](https://www.cometapi.com/models/)
* [Help Center](https://apidoc.cometapi.com/support/help-center.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.