# agnes-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for the [Agnes AI API](https://agnes-ai.com/doc/overview) 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

```bash
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

```bash
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):

```json
{
  "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):

```bash
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
```