Skip to main content
Glama

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.

Related MCP server: mcp-media-engine

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

Available Tools

7 tools
agnes_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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers