OmniaKey MCP

Local MCP server connecting coding agents to text, image, video and music AI models through the OmniaKey API.

Documentation

Models insideyour agent

Connect your AI assistant to OmniaKey through a remote MCP URL and browser authorization.

Streamable HTTP · OAuth · dedicated API key View source

Prepare a limited API key

Open API keys in your dashboard. Create a dedicated MCP key, disable unlimited quota, set a small spending limit and an expiration date, then select the models you need.

Get an API key

https://api.omniakey.com/mcp

Copy this exact URL into your MCP client. Use HTTP with OAuth. The URL ending in /mcp/ is the setup webpage; it is not the protocol endpoint.

Add OmniaKey to your client

Choose your client and copy its configuration. If an omniakey entry already exists, replace the old entry before adding it again. Keep keys out of commands and configuration files.

codex mcp add omniakey --url https://api.omniakey.com/mcp
codex mcp login omniakey

Run these commands in a terminal with Codex CLI installed. The login command opens browser authorization. Return to Codex after approval and reload the connection or start a new session.

Official client instructions

Authorize in your browser

The client opens api.omniakey.com/mcp/oauth/authorize. Check the address and callback destination before entering your dedicated key.

Paste the key only into the authorization page's password field. It is encrypted by the service; your assistant receives a separate OAuth token.
For the first connection, keep read access only. Leave paid generation and cancellation unchecked.
Choose a one-hour connection for your first check, then select Connect. If you later enable generation, choose a daily request limit too; request counts are separate from the key's spending budget.

Verify without generating

Return to your client and send this prompt. Model discovery and schema checks do not submit a generation request.

Confirm that OmniaKey MCP or CLI is ready. List accessible models and read the common media request schema. Do not submit a generation task.

A successful read-only connection exposes omniakey_models, omniakey_schema, omniakey_get_task and omniakey_wait_task. The model list must return successfully; a connected badge alone does not verify API access.

Enable generation or revoke access

To generate, reconnect with generation permission and review the model price first. Text needs max_tokens or max_completion_tokens from 1 to 4096. Manage connections with the same key; revocation stops new calls, while submitted work may finish.

Manage or revoke connections

Find your model

Query models available to your API key, then check their documented capabilities and current prices.

Make one request

Use the same OmniaKey API for text and asynchronous image, video or audio tasks.

Pick up where you left off

Keep the task id and continue checking it. A local timeout never starts a second generation.

One task, from input to output

After enabling generation, ask the assistant to review the model and inputs before submitting one paid task. Keep the returned ID to retrieve the result.

Find an image model available to my key and show its required inputs and current price. Wait for my confirmation before generating one image. Submit once with a stable idempotency key, keep the task ID and use that ID to check progress. Do not resubmit if waiting times out.

Tools the server exposes

Remote connections expose only the tools you authorize. Read access includes models, schema and task status. Generation and cancellation require separate permissions.

Tool	What it does	Required permission
`omniakey_models`	List models available to your API key, with an optional search term and result limit.	Read-only
`omniakey_schema`	Return the common chat or media request envelope without a network request.	Read-only
`omniakey_chat`	Run one non-streaming chat completion. Use it only when the user asked for generation.	Paid generation
`omniakey_submit_task`	Submit a paid image, video or audio task with a stable idempotency key.	Paid generation
`omniakey_get_task`	Read a task by id, including fresh signed asset URLs when it has succeeded.	Read-only
`omniakey_wait_task`	Wait up to 45 seconds for a task; a local timeout does not cancel or resubmit it.	Read-only
`omniakey_cancel_task`	Request cancellation of an existing task. Cancellation can remain processing, so query the status to confirm.	Cancellation request

Run locally with stdio

For a local connection, use Node.js 22+, npm and Git. Your client starts the server and reads the key from its environment.

Show local configuration and environment setup

Choose your client configuration below. The server runs locally over stdio; restart the client after configuring its environment.

[mcp_servers.omniakey]
command = "npx"
args = ["--yes", "github:omniakey-com/omniakey-devtools#v0.1.0", "mcp"]
env_vars = ["OMNIAKEY_API_KEY"]

Paste your key at the hidden terminal prompt and press Enter. Start your agent from this environment; never put the key in a prompt or repository.

read -s OMNIAKEY_API_KEY
export OMNIAKEY_API_KEY

Reload the MCP connection, then ask your agent to run this read-only check. A missing key means the client has not inherited your environment.

Troubleshooting

Check the connection mode, authorization and key policy before retrying a request.

Authorization rejects my key

Disable unlimited quota, set an expiration date and check the key is active. Model permissions and IP restrictions must allow remote Worker requests.

I see 401 or cannot connect

Opening /mcp directly without OAuth returns 401 as expected. Connect from your MCP client and complete browser authorization. A 403 or HTML response may be an edge block; use the exact endpoint and check client access.

Generation tools are missing

Read-only connections show four tools. Reconnect and explicitly allow paid generation to add chat and media submission. Cancellation has its own permission.

A request timed out or the connection expired

Keep the task ID and query it; do not create a second task. Reauthorize an expired connection. If a key was exposed, disable it in the dashboard.

About this tool

Streamable HTTP · OAuth

Remote MCP is hosted by OmniaKey. Local CLI/stdio examples use the v0.1.0 source release. Both expose the same public model and task APIs.

License

MIT

Architecture

MCP client → OAuth service → api.omniakey.com/v1

Tests

Protocol and security tests use synthetic upstream responses. They do not submit real paid generations.

Key handling

This tutorial does not collect keys. Only the API-host authorization form receives the dedicated key and encrypts it. The client receives a separate, revocable token.

Repository Security policy

Common questions

Does this change model pricing?

No. The tools use your existing API key and the gateway's billing rules. Model discovery and local schema checks do not submit generation; chat and media generation can incur charges.

What happens when waiting times out?

The remote task is not canceled or resubmitted. Keep its id and continue with task get or task wait. Successful asset URLs expire; query the same task for fresh links.

Is there a hosted MCP URL?

Yes. Use https://api.omniakey.com/mcp with Streamable HTTP and OAuth. This guide walks through remote setup; local stdio instructions remain below.

Can the agent download generated files?

No. Task tools return metadata and signed asset URLs. Download files with your own tooling while the URLs are valid.

Does the MCP server execute tool calls returned by a model?

No. It exposes OmniaKey operations to the client; the client and the user decide which calls to make. Generation requires an explicit user request.