Skip to Content
DocumentationMCP server

MCP server

For OpenClaw model configuration and a local media skill, use the OpenClaw guide. The model provider and media tools are separate connections.

API Stock runs a remote Model Context Protocol server. Connect an AI agent to it and the agent can browse models and prices, create generations from your balance and fetch the results — without an API key in its configuration. You sign in once in the browser and approve the client.

Clients can discover the server and list tool descriptions and input schemas without signing in. Calling any tool requires OAuth, including the read-only tools. Authenticate during setup with the commands below, or use a client that starts sign-in when a tool call returns an HTTP 401 challenge.

https://api.api-stock.com/mcp

Machine-readable API discovery is available without an account at /.well-known/api-catalog. The provider profile links to the public OpenAPI, pricing, signup and OAuth metadata. These documents do not authorize tool calls or spend balance.

Connect Claude Code

claude mcp add --transport http api-stock https://api.api-stock.com/mcp

Then type /mcp inside Claude Code, choose api-stock and authenticate. A browser window opens on API Stock: sign in, review what the client asks for and press Allow. Claude Code stores the token and renews it on its own.

Ask for something to check the connection:

List the video models on API Stock and what a 5-second clip costs on each.

The server is also packaged as a Claude Code plugin in APIStock/api-stock-mcp:

/plugin marketplace add APIStock/api-stock-mcp /plugin install api-stock@api-stock

Connect Codex

Codex CLI and its IDE extension use the same MCP configuration. Add the server with its Streamable HTTP URL:

codex mcp add api-stock --url https://api.api-stock.com/mcp

If adding the server starts browser authentication, sign in and approve access. Otherwise, start authentication explicitly:

codex mcp login api-stock

Restart Codex or reload the IDE extension after setup. In the Codex terminal interface, use /mcp to check the connection, then ask it to call list_models and get_account.

You can also add the server to ~/.codex/config.toml instead of using the add command, then run the login command:

[mcp_servers.api-stock] url = "https://api.api-stock.com/mcp"

No API key, client secret or manually copied token is needed. The server supports OAuth dynamic client registration; Codex registers itself and stores its credentials. See the Codex MCP documentation.

Connect OpenCode

Merge this entry into your project’s opencode.json, preserving existing configuration:

{ "$schema": "https://opencode.ai/config.json", "mcp": { "api-stock": { "type": "remote", "url": "https://api.api-stock.com/mcp", "enabled": true } } }

Run opencode mcp auth api-stock, complete browser sign-in and review consent. Use opencode mcp list to inspect the connection. Leave OAuth enabled; an API key is not an MCP access token. For connection diagnostics, use opencode mcp debug api-stock. See OpenCode’s MCP documentation.

Tasks for your agent

The agent media guide contains briefs for a page illustration, an app image asset and a draft content kit. Each asks for an estimate and spending approval before generation. MCP adds media tools alongside the coding model already selected in the client.

Connect Cursor

Use the Cursor setup guide for one-click installation, or merge this into .cursor/mcp.json in your project (~/.cursor/mcp.json applies to all projects):

{ "mcpServers": { "api-stock": { "url": "https://api.api-stock.com/mcp" } } }

Enable the server in Cursor’s MCP settings and follow the sign-in prompt. Approve access in the browser, then ask Cursor to call get_account and list_models to check the connection without a paid generation. This adds media tools alongside your selected Cursor model. API-key chat routing is configured separately; the guide explains its protocol limits.

The server supports Cursor’s HTTPS and localhost callbacks, and its desktop cursor://anysphere.cursor-mcp/oauth/callback address. Installation links use a different cursor:// address and are not OAuth callbacks.

Test locally

Run the API in development mode on port 5000 and the storefront on port 3000, with its SERVER_INTERNAL_URL set to http://127.0.0.1:5000. Both must run on the same machine as Codex and your browser. The development OAuth discovery expects the storefront on port 3000.

Open the storefront at http://api-stock.localhost:3000 and connect to:

codex mcp add api-stock-local --url http://api-stock.localhost:5000/mcp codex mcp login api-stock-local

Sign in with a local account and approve access. Use list_models and get_account to check the connection without spending any balance. The dashboard’s connection commands show the production endpoint; use the local commands above for this check.

Other clients

Other clients that support remote MCP servers over Streamable HTTP with OAuth use the same URL. Clients that browse the official MCP Registry find it as io.github.APIStock/api-stock. The client discovers the authorization server from the endpoint, registers itself and opens the browser for you; there is nothing to create in the dashboard beforehand.

The server supports Client ID Metadata Documents (CIMD) and OAuth dynamic client registration (DCR). Clients can identify themselves with an HTTPS metadata URL or register through DCR. DCR callbacks use a loopback address or an https URL. Cursor’s exact desktop callback is also classified as a native client redirect.

Note: the server takes OAuth access tokens only. An API key in the Authorization header is not accepted on /mcp — keep using the key for the HTTP API.

Tools

ToolWhat it doesNeeds
list_modelsVideo, image and music models with their starting price.read
get_modelParameters, price table and an example request for one model.read
estimate_costThe exact price of a request. Nothing is created or charged.read
create_generationStarts a generation and returns a taskId. Charges the balance.generate
create_upload_urlA signed PUT URL for one local input file and its public URL.generate
get_taskStatus of a task and the file URLs once it has finished.read
list_generationsYour recent generations, newest first.read
get_accountThe balance and a link to top it up.read

Generation is asynchronous, exactly as in the HTTP API: create_generation returns at once, and the result arrives later. get_task takes waitSeconds (up to 30) so an agent can wait for the result instead of polling in a loop. Input images, video and audio are passed as public URLs.

For a local file, call create_upload_url with its exact contentLength in bytes and contentType. PUT the file bytes to the returned uploadUrl with the returned headers. After the upload succeeds, pass publicUrl as the model’s input URL. The agent needs an HTTP upload tool alongside MCP.

Files must be between 1 byte and 25 MiB. Supported MIME types are image/png, image/jpeg, image/webp, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/wav and audio/mp4. The URL expires after 10 minutes. Upload is free and requires a positive balance; each user can request at most 20 upload URLs per minute across their MCP clients.

create_generation accepts the same model and input as POST /generation/create, plus two optional safeguards:

FieldMeaning
maxCostUsdRefuse the request if it would cost more than this.
idempotencyKeyRepeating the call with the same key and request returns the same task instead of charging again.

Permissions

A client asks for permissions when it connects, and the consent screen lists them:

PermissionLets the client
mcp:readSee models, prices, your generations and your balance.
mcp:generateCreate generations. This spends your balance.
offline_accessStay connected without asking you to sign in again.

A client that was given mcp:read only cannot create generations; it is asked to authorize again if it tries.

mcp:generate also allows creating input upload URLs.

Disconnect a client

Open Dashboard → Connectors. Every connected client is listed there with the date it was connected; Disconnect takes effect immediately, including for a session the client already has open.

Changing or resetting your password also disconnects all MCP clients on both storefronts. Reconnect and approve access again to continue.

Costs and failures

A generation started through MCP costs exactly what the same request costs through the HTTP API, and is charged from the same prepaid balance. A failed generation is refunded automatically. When the balance is too low the tool answers with an error and a link to the billing page.