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	agnes_chat	agnes-2.0-flash, agnes-1.5-flash
2	Image generation & editing	agnes_image	agnes-image-2.1-flash, agnes-image-2.0-flash
3	Video & audio-video generation (async)	agnes_video_create, agnes_video_query, agnes_video_wait	agnes-video-v2.0
4	Multimodal understanding	agnes_vision (+ image input in agnes_chat)	agnes-2.0-flash, agnes-1.5-flash
–	Model discovery	agnes_models	all

Highlights

• 1M context — agnes_chat / agnes_vision accept max_tokens up to 1,048,576; agnes-2.0-flash supports a 1M-token context window.
• 4K video — agnes_video_create accepts width/height up to 3840 (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_thinking and Anthropic-style thinking.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-form extra_body passthrough.
• Resilience — automatic retry with exponential backoff for transient errors (429 capacity/cooldown, 5xx), as recommended by the Agnes error-code docs.
• Streaming — stream: true is consumed server-side and returned as assembled text.

Setup

cd agnes-mcp
npm install
npm run build

Configure your API key in .env (already created):

AGNES_API_KEY=sk-...

Optional override:

AGNES_BASE_URL=https://apihub.agnes-ai.com/v1

Run

npm start            # node dist/index.js  (stdio transport)
npm run dev          # tsx src/index.ts

Integrate 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 listing

The 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: true does not actually populate b64_json. This server normalizes it to extra_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 legacy GET /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.json