CometAPI MCP

The CometAPI MCP server connects Model Context Protocol 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. 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. 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

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:

export COMETAPI_KEY="<COMETAPI_KEY>"

Add the server

Claude Code
Codex
Other clients

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:

{
  "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.

Add the server with the Codex CLI:

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.

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:

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:

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:

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:

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:

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.

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.

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	You work in a terminal or a script, or you need account data such as balance and usage logs
CometAPI API	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. 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 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 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.

Troubleshooting

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. The server does not accept account access tokens.

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.

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.

Start here

Model API quickstarts

Core API guides

Developer tools

Errors

Pricing and billing

Support

Features

Prerequisites

Connect a client

Try example prompts

Tools

Choose the MCP server, the API, or the CLI

Billing

Troubleshooting

Links

​Features

​Prerequisites

​Connect a client

​Try example prompts

​Tools

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

​Billing

​Troubleshooting

​Links

Features

Prerequisites

Connect a client

Try example prompts

Tools

Choose the MCP server, the API, or the CLI

Billing

Troubleshooting

Links