# Kourier MCP Server

[![Kourier MCP connector – tool definition quality and endpoint health on Glama](https://glama.ai/mcp/connectors/sh.kourier/info/badges/score.svg)](https://glama.ai/mcp/connectors/sh.kourier/info)
[![smithery badge](https://smithery.ai/badge/kourier/info)](https://smithery.ai/servers/kourier/info)

Remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Kourier](https://kourier.sh) — **flat-rate hosted AI inference for coding agents**.

Use the MCP server to discover plans, check model limits, configure your coding client, start human-approved subscription onboarding, and submit account-attributed feedback or error reports. Kourier serves DeepSeek V4.1 Flash through OpenAI-compatible and Anthropic-compatible inference APIs, with no per-token billing or request-volume quotas. Plans differ by concurrency.

```text
https://kourier.sh/mcp
```

**Transport:** Streamable HTTP, stateless, JSON responses. **Authentication:** none required for information or onboarding; `submit_feedback` requires a Kourier API key in the connection's `Authorization: Bearer` header.

> MCP provides service information and setup instructions, not model inference. Inference uses a subscription API key at `https://api.kourier.sh/v1` (OpenAI-compatible) or `https://api.kourier.sh/anthropic` (Anthropic-compatible).

This repository documents the hosted service; there is no local server to install or run. The live MCP server provides eight tools: four read-only information tools, three onboarding tools, and one authenticated feedback tool. Recurring billing and agent access require explicit human approval in the browser before a dedicated inference key can be issued.

## Quick start

### Claude Code

```bash
claude mcp add --transport http kourier https://kourier.sh/mcp
```

### Cursor / clients using `mcpServers`

Add this entry to your client's MCP configuration:

```json
{
  "mcpServers": {
    "kourier": {
      "url": "https://kourier.sh/mcp"
    }
  }
}
```

Configuration formats vary by client; use the remote Streamable HTTP URL above where your client requests a server URL.

Once connected, ask: **“What are Kourier's plans, and how do I configure my coding client to use it?”**

Adding this MCP server does not change the model powering your coding client. Use `get_setup_instructions` to configure Kourier as the inference provider separately.

## Tools

Connecting to MCP and using the information or onboarding tools requires no connection credentials. Onboarding status and completion require the private `onboarding_token` returned by `create_checkout_link`. Only `submit_feedback` requires an API-key bearer header. Keep tokens and keys out of logs, public messages, report content, and repositories.

| Tool | Arguments | What it does |
| --- | --- | --- |
| `get_pricing` | None | Returns public plans, monthly prices, concurrency limits, and usage-cap information. |
| `get_models` | None | Returns the served model's exact API identifier and context/output limits. |
| `get_api_key_instructions` | None | Explains dashboard signup, agent sign-in, and OAuth with PKCE. Does not return an API key itself. |
| `get_setup_instructions` | Optional `harness` | Returns configuration guidance for `oh-my-pi`, `claude-code`, `codex`, or `openai-compatible`. Omit the argument for generic OpenAI-compatible settings. |
| `create_checkout_link` | `plan`, `client_name`; optional `harness` | Starts verified sign-in, recurring Starter/Pro purchase, and explicit agent-access approval. Returns a browser link and approval code; creating the link does not itself charge or issue a key. |
| `get_onboarding_status` | Private `onboarding_token` | Checks approval and entitlement status. Poll every five seconds; complete only when ready, and stop on issued, denied, or expired. |
| `complete_onboarding` | Private `onboarding_token` | Exchanges ready onboarding for a dedicated revocable inference key once. Save it securely; never retry after issuance or ambiguous delivery—check status instead. |
| `submit_feedback` | `kind`, `message`; optional `request_id`, `client_name` | Saves account-attributed feedback or an error report. Requires a Kourier API key in the connection's `Authorization: Bearer` header, never in tool arguments. |

For example, call `get_setup_instructions` with:

```json
{
  "harness": "claude-code"
}
```

The server also exposes the **`kourier-setup`** Markdown resource and the **`configure_kourier`** prompt, which accepts the same optional `harness` value.

## Feedback and error reports

Use **`submit_feedback`** to send product feedback or report a Kourier error. Reports are attributed to the account that owns the API key.

### Authentication and privacy

- Configure the MCP connection with `Authorization: Bearer <your Kourier API key>`. Store the key in your client's private credential settings; never add a real key to repository configuration.
- The key must be valid, unexpired, and not revoked, and the account must not be banned. An active inference subscription is not required to report a problem using an otherwise valid key.
- The public information and onboarding tools remain available without this header. For clients with no custom-header support, those tools still work, but feedback requires a header-capable client.
- Send only information the user wants to share. Exclude API keys, onboarding tokens, passwords, personal data, and private code or logs. A sanitized Kourier request ID can help investigate an error.

### Arguments

| Argument | Required | Value |
| --- | --- | --- |
| `kind` | Yes | `feedback` for product feedback, or `error` for an error report. |
| `message` | Yes | Nonblank text, 1–8,000 characters after trimming. For errors, describe expected behavior, actual behavior, and reproduction steps without private data. |
| `request_id` | No | A Kourier request ID associated with the error, 1–200 characters after trimming. |
| `client_name` | No | Client or harness name and version, 1–80 characters after trimming. |

NUL bytes, blank supplied strings, extra fields, and credential arguments are not accepted.

### Example

The following command **saves a feedback report** when run with a valid key. Replace the sample message with feedback the user has approved, and set `KOURIER_API_KEY` privately in your environment before running it:

```bash
curl https://kourier.sh/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $KOURIER_API_KEY" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "submit_feedback",
      "arguments": {
        "kind": "feedback",
        "message": "Please add more coding-client setup examples to the documentation.",
        "client_name": "curl"
      }
    }
  }'
```

Successful submissions return a receipt with `id` and `created_at` in `result.structuredContent`; the same receipt is included as JSON text in `result.content`. Tool failures set `result.isError` to `true` and return `error` and `error_description`.

- **`unauthorized`** — configure a valid Kourier API-key bearer header.
- **`invalid_arguments`** — correct the submitted fields and limits above.
- **`rate_limited`** — wait the number of seconds in `retry_after` before submitting again.
- **`service_unavailable`** — receipt could not be confirmed. The report may already have been saved; do not blindly retry, because another submission can create a duplicate.

## Hosted inference

### Plans

| Plan | Monthly price (USD) | Concurrent requests |
| --- | --- | --- |
| Starter | $20 | 1 |
| Pro | $50 | 3 |

Neither public plan has a five-hour, weekly, or monthly request or token quota. A concurrency slot becomes available when its request finishes. “No usage quotas” does not mean unlimited simultaneous requests.

Consult [`get_pricing`](https://kourier.sh/mcp) or [the pricing page](https://kourier.sh/pricing) for current terms; the MCP endpoint accepts JSON-RPC POST requests, not ordinary browser GET requests.

### Model and endpoints

| Setting | Value |
| --- | --- |
| Model | DeepSeek V4.1 Flash |
| Exact API model identifier | `deepseek-v4.1-flash` |
| OpenAI-compatible base URL | `https://api.kourier.sh/v1` |
| Anthropic-compatible base URL | `https://api.kourier.sh/anthropic` |
| Maximum combined prompt + output context | 262,144 tokens (256K) |
| Maximum output per response | 16,384 tokens |
| Authentication | `Authorization: Bearer <key>`; the Anthropic surface also accepts `x-api-key` |

Use the exact model identifier; aliases are not supported. Check `get_models` and [the model documentation](https://docs.kourier.sh/docs/models) for current availability and limits.

## Getting connected

1. [Create an account](https://app.kourier.sh/signup).
2. Choose Starter or Pro in Billing.
3. Create an API key in Dashboard → API Keys.
4. Call `get_setup_instructions` for your client and apply the returned settings.

For agent-assisted sign-in, follow [Kourier's auth.md](https://kourier.sh/auth.md) and [the agent sign-in guide](https://docs.kourier.sh/docs/agent-sign-in). Human approval happens in the browser; connecting to the public MCP server alone does not authorize billing or grant inference access.

Keep API keys in environment variables or your client's private credential store. Never commit them to a repository or paste them into public issues. The public information tools do not need your inference key.

### Inference request with curl

With an active subscription and `KOURIER_API_KEY` set in your environment:

```bash
curl https://api.kourier.sh/v1/chat/completions \
  -H "Authorization: Bearer $KOURIER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "Explain what this coding API supports."}],
    "max_tokens": 256
  }'
```

## Verify the MCP connection

Send an initialization request without an API key:

```bash
curl https://kourier.sh/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {"name": "kourier-quickstart", "version": "1.0.0"}
    }
  }'
```

The response identifies the server as `kourier-info` and advertises tools, resources, and prompts. Supported protocol versions are `2025-11-25`, `2025-06-18`, and `2025-03-26`.

List the available tools:

```bash
curl https://kourier.sh/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

The endpoint does not offer a persistent SSE stream or MCP sessions. `GET` and `DELETE` return `405`; use JSON-RPC `POST`. Normal MCP clients handle protocol initialization automatically.

## Links

The hosted service is published in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers/sh.kourier%2Finfo/versions/latest) as **`sh.kourier/info`**. The repository includes `server.json` for registry metadata, `glama.json` for maintainer verification, and `lhm.plugin.json` for LobeHub publication. Directory account verification and review are separate from registry publication.

- **Website:** [kourier.sh](https://kourier.sh)
- **Pricing:** [kourier.sh/pricing](https://kourier.sh/pricing)
- **Dashboard:** [app.kourier.sh](https://app.kourier.sh)
- **Documentation:** [docs.kourier.sh/docs](https://docs.kourier.sh/docs)
- **Agent sign-in:** [kourier.sh/auth.md](https://kourier.sh/auth.md)
- **MCP server card:** [kourier.sh/.well-known/mcp/server-card.json](https://kourier.sh/.well-known/mcp/server-card.json)
- **Setup skill:** [kourier-setup/SKILL.md](https://kourier.sh/.well-known/agent-skills/kourier-setup/SKILL.md)

For documentation corrections, open an issue in this repository. For account or billing help, use the support options on Kourier's website or dashboard; do not disclose account credentials here.