Skip to main content
Glama
README.md
# Medux MCP Server

Connect AI assistants to [Medux](https://medux.io) for AI media generation and editing: video, image, speech, voice cloning, avatars, and PDF/audio/video tools.

| | |
| --- | --- |
| Endpoint (Streamable HTTP) | `https://medux.io/mcp` |
| Authentication | OAuth sign-in, or `Authorization: Bearer sk-medux-...` |
| Tools | 60+ (generation, editing, conversion, account, task query) |

> **Endpoint change:** the canonical endpoint is now `https://medux.io/mcp`.
> The old `https://medux.io/api/mcp/v1` still works, and existing API keys and OAuth grants stay valid.

## Quick start by client

| Client | Setup | Auth |
| --- | --- | --- |
| Codex | `codex mcp add medux --url https://medux.io/mcp` then `codex mcp login medux` | OAuth |
| Claude Code | `claude mcp add --transport http medux https://medux.io/mcp`, then `/mcp` → Authenticate | OAuth |
| claude.ai / Claude Desktop | Customize → Connectors → Add custom connector → `https://medux.io/mcp` | OAuth |
| Cursor | [medux-cursor-plugin](https://github.com/MeduxIO/medux-cursor-plugin) | API key |
| VS Code / GitHub Copilot | see [below](#github-copilot--vs-code) | API key |

Step-by-step guides, tool overview and troubleshooting for Codex and Claude live in
[medux-mcp-examples](https://github.com/MeduxIO/medux-mcp-examples/blob/main/docs/connection.md).

## Authentication

- **OAuth (recommended):** clients register automatically (DCR) and use authorization code + PKCE. Sign in to Medux in the browser and approve access. Tokens grant only `mcp:tools`, refresh automatically, and the authorization expires after 30 days.
- **API key:** create a key (starts with `sk-medux-`) in your Medux account at <https://medux.io> and send it as a Bearer token. Keep it secret; never commit it.

## GitHub Copilot / VS Code

Requires VS Code 1.99+ with GitHub Copilot signed in, and Copilot Chat in **Agent** mode.

1. Run **MCP: Open User Configuration** from the Command Palette (⇧⌘P / Ctrl+Shift+P).
2. Add the server:

   ```json
   {
     "servers": {
       "medux": {
         "type": "http",
         "url": "https://medux.io/mcp",
         "headers": { "Authorization": "Bearer ${input:medux-api-key}" }
       }
     },
     "inputs": [
       { "type": "promptString", "id": "medux-api-key", "description": "Medux API key", "password": true }
     ]
   }
   ```

3. In the MCP Servers list, open the gear next to `medux` and choose **Start Server** (or **Restart Server**).
4. In Copilot Chat (Agent mode) open the tools picker and confirm the `medux` tools are listed.
5. Try a harmless request first, for example: "Use medux to check my balance".

If the key prompt never appears (tool calls end with `Canceled` or `401`), put the key directly in the header of your **user-level** `mcp.json` (never in a repository), then restart the server:

```json
"headers": { "Authorization": "Bearer sk-medux-xxxxxxxx" }
```

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| `401` / unauthorized | Missing `Bearer ` prefix, wrong or revoked key, or expired OAuth sign-in |
| `Canceled: Canceled` on every call (VS Code) | The key prompt was not answered; use the direct-header form |
| `404` with `NOT_FOUND` | The request reached Medux; the task or resource id does not exist |
| Server not listed | Check the config saved correctly; view logs via the gear → **Show Output** |
| Worked on `/api/mcp/v1`, fails on `/mcp` | Remove the server and add it again with the new URL; re-authenticate |

## Registry

Published to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.MeduxIO/medux`
through `.github/workflows/publish-mcp.yml` (GitHub OIDC).
To release a new version: bump `version` in `server.json`, then run the workflow or push a `v*` tag.

## License

MIT