Connect your agent with MCP

Sogni supports Model Context Protocol (MCP) through the Creative Agent Skill's local server. A separate hosted server provides a remote tool surface for image, video, audio and durable creative jobs.

Hosted availability — November 4, 2026: The hosted endpoint is not publicly deployed. The hosted sections below document its connection and tool contract; use the local MCP integration for an available connection today.

#Connect with local MCP

Install the Creative Agent Skill's local MCP server for a compatible client. See the same guide for Codex, or the repository's Goose setup. The local server runs the installed CLI on your computer and supports local media, saved personas, memories and editing utilities. Its tool names and inputs differ from the hosted contract below.

#Hosted connection reference

The hosted integration lets an external agent use Sogni's remote tools with a developer API key, without installing the Sogni skill or CLI. Configure this connection only after the availability note above confirms the public service is deployed.

Use a client that supports remote Streamable HTTP MCP and a Bearer token or custom Authorization header. A client that accepts only local stdio servers or OAuth sign-in needs a different integration. Client support for remote MCP alone does not establish support for API-key authentication.

1. Create a dedicated developer key on the API Keys page. Choose the key's spending limits, model access and expiry for this agent.
2. Add a remote MCP server in your client using these settings:

If the client asks for a custom header, its name is Authorization and its value is Bearer YOUR_SOGNI_API_KEY. Replace the placeholder in the client's secret field. If it has a dedicated Bearer-token field, enter only the key there. Keep the key out of prompts, URLs, repositories and screenshots.

3. Connect and refresh the client's tool list. Sogni exposes the twelve tools listed below.
4. Ask your agent to call get_balance and list_models with network: "fast". Check account access, subscription status and available models before submitting work.

OAuth sign-in is not supported by this API-key connection. Browser session tokens and worker keys are not accepted. An IP-restricted key is checked against the hosted gateway's connection, so an allowlist containing only your laptop's IP will not work. See authentication for key management.

#Make your first image

Ask the connected agent:

Use Sogni to create one image of a red ceramic cup on a wooden table.
Check my account and the available Fast image models first. Quote the
chosen model at its supported dimensions and tell me whether my
subscription covers it. Wait for my approval of any token charge.
Keep the request ID and returned job ID so a disconnect does not
create a duplicate. Show me the result when it finishes.

The agent should choose a concrete model ID from list_models, call quote with the intended tool and exact generation arguments, then submit those same arguments to generate_image after the cost is authorized. Quotes do not start renders. An unavailable estimate is not a zero-cost estimate.

Use a distinct request_id for each new operation. Retry an uncertain submission with the same ID and arguments. Changing the ID can start and charge for another job. An explicit model choice remains bound; select another model yourself if it is unavailable.

#Tools

Your client receives each tool's input schema during discovery. Model-specific inputs remain subject to the selected model's contract. Use parameters for supported native arguments; do not duplicate the named MCP fields there. Generic image-to-image on base image generators is not supported: choose an image-edit model for reference-based edits.

#Unlimited and token billing

The tools use your existing Sogni account. Eligible requests can use its Unlimited subscription; premium models retain their normal charges. billing_mode accepts auto, subscription or tokens, and token_type accepts auto, spark or sogni where the operation supports it. Check the quote's covered_by_subscription separately from its estimated token value. A model's catalog entry alone is not proof of account coverage.

Hosted MCP generation runs on Fast. Choosing subscription billing does not move a job to Relaxed. The network filter on list_models changes discovery only.

Developer-key spending limits still apply, including the Spark value of subscription-covered work. A quote is an estimate, not a reservation or permission to spend. run_creative_agent can make multiple tool calls and use billed LLM inference; it is not a fixed-price quote for an entire brief. See pricing and funding and billing controls.

#Reference media

Call create_upload with a matching media_type and MIME content_type, such as image and image/png. Send the file directly to the returned upload_url using its method and every returned upload_fields entry. Signed POST uploads use multipart form data, including the file, within max_size_bytes.

After the upload succeeds, pass download_url to the generation tool's appropriate reference field. Do not pass the upload URL, a local filename or an unuploaded path. Use original stills for image-to-video and first/last-frame inputs, with the model's required aspect ratio and dimensions.

#Jobs, approvals and reconnecting

Successful tools return structured content with kind and data. A generation response contains data.job_id and data.kind. Save both: media operations return kind: "workflow"; run_creative_agent returns kind: "run". Call get_job with those values after a reconnect. Jobs continue independently of the MCP connection; closing the client does not cancel them.

When the job needs cost approval, retrieve its current approval object and show the preview to the user. Pass that object unchanged to approve_cost with the job ID, kind, decision: "confirm" and a stable new approval request_id. Use decision: "cancel" to decline. Never reconstruct a different price or automatically approve a changed preview.

If the creative agent asks for clarification, read the returned message and submit a complete revised brief with a new request ID. The hosted MCP tools do not provide an interactive message-resume operation.

Results include artifacts and HTTPS output links. When next_artifact_offset is present, call get_job again with that artifact_offset to retrieve the next page. Download assets you want to keep promptly; signed links expire. Cancellation cannot undo work already completed. See jobs and assets.

#Troubleshooting

#Hosted MCP, skills and Worlds

Hosted MCP suits remote agent platforms and applications that can connect an MCP server with an API key. The Creative Agent Skill adds local workflow instructions, CLI access, personas, memories and media utilities. Its bundled local MCP server runs on your computer and has its own setup and tool surface. You can keep using that integration.

The hosted tool set does not expose a Sogni Worlds builder or install the Worlds Kit. Use the Sogni Worlds guides for that workflow. MCP supplies the tools advertised by this server; it does not install a skill into the external agent.