# @mafdet/mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that brings
**read-only Mafdet AI account tools** into Claude Code, Claude Desktop, Cursor,
Codex CLI, OpenCode, and any other MCP client.

It does **not** run model inference — you keep calling Mafdet AI models through
each tool's normal OpenAI-compatible endpoint. This server only exposes
read-only account and documentation helpers.

## What Mafdet AI is

Mafdet AI is an OpenAI-compatible AI gateway: one API key and one base URL reach
models from several providers, billed by usage. Any tool or SDK that speaks the
OpenAI API works by pointing its base URL and key at Mafdet AI.

- Base URL: `https://api.mafdet.ai/v1`
- Endpoints: `/chat/completions`, `/embeddings`, `/audio/speech`
- Providers: Google (Gemini), Kimi (Moonshot), Qwen, DeepSeek
- 30 models as of August 2026. The catalogue changes, so the authoritative list
  with current prices is [`models.json`](https://docs.mafdet.ai/models.json)
- Docs: <https://docs.mafdet.ai>

## Tools

| Tool | Needs a key | What it does |
| --- | --- | --- |
| `list_models` | no | List Mafdet AI models with provider, tier, per-1M-token pricing, and a `[preview]` / `[beta]` marker for models the provider has not declared generally available |
| `search_docs` | no | Search the Mafdet AI documentation (titles, URLs, summaries) |
| `get_balance` | yes | Your organization's wallet: balance, bonus, frozen, available |
| `get_usage_summary` | yes | Requests, tokens, and charge over the last N days (1–90) |
| `get_subscription` | yes | Current plan, status, period, and Playground credit |

The account tools are **read-only** — there is no key management, recharge,
refund, subscription change, or any write operation.

## Configuration

Set these environment variables (all optional):

- `MAFDET_API_KEY` — a Mafdet AI key **with the `account:read` scope**. Only the
  account tools need it; `list_models` and `search_docs` work without a key.
  Create a key with the scope in the Console (API Keys → "Allow the local MCP
  server to read this account"). Prefer your client's secret/env configuration
  over putting the key on a command line.
- `MAFDET_BASE_URL` — defaults to `https://backend.mafdet.ai`. Only change it for
  local/staging testing; it must be an `https://` URL.
- `MAFDET_DOCS_URL` — defaults to `https://docs.mafdet.ai`.

## Client setup

### Claude Code

```sh
claude mcp add mafdet --env MAFDET_API_KEY=sk-mafdet-live-... -- npx -y @mafdet/mcp
```

### Claude Desktop / Cursor / other MCP clients

Add to the client's MCP config (`claude_desktop_config.json`, Cursor MCP
settings, etc.):

```json
{
  "mcpServers": {
    "mafdet": {
      "command": "npx",
      "args": ["-y", "@mafdet/mcp"],
      "env": { "MAFDET_API_KEY": "sk-mafdet-live-..." }
    }
  }
}
```

### Codex CLI (`~/.codex/config.toml`)

```toml
[mcp_servers.mafdet]
command = "npx"
args = ["-y", "@mafdet/mcp"]
env = { MAFDET_API_KEY = "sk-mafdet-live-..." }
```

### OpenCode (`opencode.json`)

```json
{
  "mcp": {
    "mafdet": {
      "type": "local",
      "command": ["npx", "-y", "@mafdet/mcp"],
      "environment": { "MAFDET_API_KEY": "sk-mafdet-live-..." }
    }
  }
}
```

Omit `MAFDET_API_KEY` to use only the public tools (`list_models`,
`search_docs`).

## Notes

- Pin a major version (`@mafdet/mcp@0`) in automated setups to avoid surprise
  upgrades.
- The server writes only JSON-RPC to stdout; diagnostics go to stderr and never
  include your key.
- Requires Node.js 20+.