agnes-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agnes-mcp generate an image of a cat wearing a hat"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agnes-mcp
An MCP (Model Context Protocol) server for the Agnes AI API by Sapiens AI.
It exposes all four documented core capabilities as MCP tools, integrates every Agnes model, and surfaces all configurable parameters — including the 1M-token context window and 4K video resolution.
Base URL:
https://apihub.agnes-ai.com/v1(OpenAI-compatible)Auth:
Authorization: Bearer <AGNES_API_KEY>
Core capabilities & tools
# | Capability | Tool(s) | Models |
1 | Text generation & reasoning |
|
|
2 | Image generation & editing |
|
|
3 | Video & audio-video generation (async) |
|
|
4 | Multimodal understanding |
|
|
– | Model discovery |
| all |
Highlights
1M context —
agnes_chat/agnes_visionacceptmax_tokensup to1,048,576;agnes-2.0-flashsupports a 1M-token context window.4K video —
agnes_video_createacceptswidth/heightup to3840(multiples of 64). The gateway auto-standardizes to the nearest supported level (480p/720p/1080p/4K).All parameters — temperature, top_p, max_tokens, stream, tools, tool_choice, Thinking mode (
chat_template_kwargs.enable_thinkingand Anthropic-stylethinking.budget_tokens), frequency/presence/repetition penalty, stop, seed, image input (URL/data-URI), response_format, return_base64, num_frames (8n+1, ≤441), frame_rate (1–60), negative_prompt, seed, and free-formextra_bodypassthrough.Resilience — automatic retry with exponential backoff for transient errors (429 capacity/cooldown, 5xx), as recommended by the Agnes error-code docs.
Streaming —
stream: trueis consumed server-side and returned as assembled text.
Related MCP server: mcp-media-engine
Setup
cd agnes-mcp
npm install
npm run buildConfigure your API key in .env (already created):
AGNES_API_KEY=sk-...Optional override:
AGNES_BASE_URL=https://apihub.agnes-ai.com/v1Run
npm start # node dist/index.js (stdio transport)
npm run dev # tsx src/index.tsIntegrate with an MCP client
Add to your client config (e.g. Claude Desktop / opencode):
{
"mcpServers": {
"agnes": {
"command": "node",
"args": ["/Users/yingjunchi/Downloads/agnes-mcp/dist/index.js"],
"env": { "AGNES_API_KEY": "sk-..." }
}
}
}Because Agnes AI is OpenAI-compatible, you can also use it directly as a model provider (Base URL https://apihub.agnes-ai.com/v1, model agnes-2.0-flash).
Tests
Every capability is verified against the live API (the key in .env must be valid):
npm test # all tests
npm run test:chat # chat: basic, multi-turn, streaming, tools, thinking, 1.5-flash
npm run test:vision # multimodal understanding
npm run test:image # text-to-image (url + base64), image-to-image, 2.0-flash
npm run test:video # create, query, wait-for-completion (slow)
npm run test:models # model listingThe video wait test polls until the task completes and asserts the final MP4 URL is returned.
API quirks handled
Image base64: the documented top-level
return_base64: truedoes not actually populateb64_json. This server normalizes it toextra_body.response_format = "b64_json", which is the working path for both text-to-image and image-to-image.Image-to-image: input images are placed in
extra_body.image(not top-level) per the 2.1 docs.Video query: uses the recommended
GET /agnesapi?video_id=(host root, not/v1) and falls back to the legacyGET /v1/videos/{task_id}.
Project layout
agnes-mcp/
├── src/
│ ├── client.ts # Agnes API client (4 capabilities, all params, retry)
│ ├── tools.ts # MCP tool definitions & handlers
│ └── index.ts # stdio MCP server entry
├── tests/ # live-API tests (models, chat, vision, image, video)
├── .env # AGNES_API_KEY (and optional overrides)
└── package.jsonAvailable Tools
7 toolsagnes_chatA
Capability 1 — Text generation & reasoning. OpenAI-compatible chat completions. Supports multi-turn conversation, system prompts, tool/function calling, streaming, and Thinking mode. Models: agnes-2.0-flash, agnes-1.5-flash. agnes-2.0-flash supports up to 1M-token context (set max_tokens up to 1048576). Vision is also available here by passing image_url content parts; use agnes_vision for a simpler image-understanding interface.
Inputs: messages (required), model, temperature, top_p, +11 more.
agnes_imageA
Capability 2 — Image generation & editing. Text-to-Image and Image-to-Image (edit/transform/multi-image compose). Models: agnes-image-2.1-flash, agnes-image-2.0-flash. Required: model, prompt, size. For image-to-image, pass 'image' (array of public URLs or data URIs). Note: image dimensions must be multiples of 16. Put response_format inside extra_body (handled automatically here).
Inputs: prompt (required), model, size, image, +3 more.
agnes_modelsA
List all available Agnes AI models (text/chat, image, video) with their limits. Useful to discover model names before calling the other tools.
Inputs: no named parameters.
agnes_video_createA
Capability 3 — Video & audio-video generation (async). Create a video task from text, a single image, multiple images, or keyframes. Model: agnes-video-v2.0. Returns task_id and video_id. Poll the result with agnes_video_query or agnes_video_wait. Highlights: width/height accept up to 4K (3840). Video dimensions must be multiples of 64. num_frames ≤ 441 and must equal 8n+1 (e.g. 81, 121, 161, 241, 441). frame_rate 1–60. seconds = num_frames / frame_rate.
Inputs: prompt (required), model, image, mode, +8 more.
agnes_video_queryA
Query the status/result of an async video task. Recommended: pass video_id (returned by agnes_video_create). Legacy: pass task_id. When status is 'completed', the final video URL is in remixed_from_video_id.
Inputs: video_id, task_id, model_name.
agnes_video_waitA
Poll an async video task (by video_id) until it reaches a terminal state (completed/failed) or times out. Returns the final result including the video URL when completed. Video generation can take tens of seconds to minutes.
Inputs: video_id (required), model_name, interval_ms, timeout_ms.
agnes_visionA
Capability 4 — Multimodal understanding. Send one or more images (public URLs or data URIs) plus a text instruction and the model describes, analyzes, OCRs, or answers questions about the visual content. Models: agnes-2.0-flash, agnes-1.5-flash (both accept image_url input).
Inputs: images (required), model, instruction, system, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct capability (chat, image, video creation, video query, video wait, vision, model listing). Slight overlap between agnes_chat and agnes_vision regarding vision tasks is clarified in descriptions, so agents can disambiguate.
All tools use 'agnes_' prefix, but naming patterns vary: some are single nouns (chat, image, models, vision) while others use verb_noun compounds (video_create, video_query, video_wait). The convention is not fully consistent but still readable.
7 tools is well-scoped for an AI API server covering text, image, video generation, and model discovery. Each tool serves a clear purpose without unnecessary overlap or missing essential operations.
Core workflows for text generation, image generation/editing, video generation (async with status polling), and vision understanding are covered. Minor gaps include no explicit tool for deleting or updating generated content, but these are typical for generation APIs.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that exposes 300+ AI agents as tools via a single API key. Supports listing agents, invoking any agent with chat-completion style messages, checking agent health, and retrieving platform statistics.54MIT
- AlicenseAqualityCmaintenanceMCP server for AI-powered image, audio, and video generation, enabling media creation directly from Claude, Cursor, and other MCP clients.1141 npmMIT
- AlicenseAqualityFmaintenanceProduction-grade MCP server for image and video understanding and generation across Gemini, OpenAI, and Grok.5114 PyPI4Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProduction-ready MCP server providing RAG, hierarchical memory, and 8+ tools for AI agents via the Model Context Protocol.54Apache 2.0