Sampling2API

Expose MCP Client Sampling as an Anthropic-compatible Messages API

English · 中文

English

Overview

sampling2api is a bridge tool written in Rust that exposes the MCP (Model Context Protocol) client's Sampling capability as a standard Anthropic Messages API (POST /v1/messages).

This allows any external service or tool that already speaks the Anthropic API to seamlessly use the AI capabilities provided by an MCP client — no external API keys or provider configuration needed.

Motivation

In the MCP ecosystem, Sampling lets servers request LLM completions from clients. However, most existing tools and libraries are built against well-known HTTP APIs (like Anthropic's). sampling2api bridges this gap: it accepts standard Anthropic Messages API requests over HTTP and forwards them as MCP sampling/createMessage calls to the connected client.

Features

• Anthropic Messages API compatible — POST /v1/messages endpoint with JSON and streaming (SSE) responses
• Two transport modes:
  • Stdio — connects to an MCP client over stdin/stdout (ideal for subprocess-based setups)
  • Streamable HTTP — connects to an MCP client over HTTP (ideal for remote or multi-client scenarios)
• Tool use support — full round-trip for tool calls, tool results, and multi-turn tool loops
• Image support — base64 image passthrough and URL image download-to-base64 conversion
• Multi-session routing — in HTTP mode, multiple MCP clients can connect simultaneously, routed via the x-mcp-session-id header
• Health check endpoint — GET /health

Installation

# Clone the repository
git clone https://github.com/anthropics/sampling2api.git
cd sampling2api

# Build with Cargo
cargo build --release

The binary will be at target/release/sampling2api.

Usage

Stdio Mode

Connect to an MCP client over stdin/stdout and expose the API on a local HTTP port:

sampling2api stdio --listen 127.0.0.1:38080

The MCP client launches sampling2api as a subprocess (or vice versa). Once connected, send requests to http://127.0.0.1:38080/v1/messages.

Streamable HTTP Mode

Run as an HTTP server that accepts both MCP client connections and API requests:

sampling2api http --listen 127.0.0.1:38080 --mcp-path /mcp

• MCP clients connect via the Streamable HTTP transport at http://127.0.0.1:38080/mcp
• API consumers send requests to http://127.0.0.1:38080/v1/messages

When multiple MCP clients are connected, use the x-mcp-session-id header to route requests to a specific session.

API Reference

POST /v1/messages

Accepts a standard Anthropic Messages API request body:

{
  "model": "claude-sonnet-4-0",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Hello, world!" }
  ],
  "stream": false
}

• Set "stream": true for Server-Sent Events (SSE) streaming responses
• Set "stream": false (or omit) for a single JSON response
• The model field is passed as a hint to the MCP client's model preferences

Headers:

GET /health

Returns ok — useful for readiness and liveness probes.

Architecture

┌──────────────┐         ┌──────────────────┐         ┌────────────┐
│  API Consumer│  HTTP    │   sampling2api   │   MCP   │ MCP Client │
│  (e.g. app)  │────────▶│                  │────────▶│ (with LLM) │
│              │◀────────│  /v1/messages     │◀────────│            │
└──────────────┘  JSON/  └──────────────────┘ sampling └────────────┘
                   SSE          Bridge         /createMessage

1. An API consumer sends an Anthropic-format request to /v1/messages
2. sampling2api converts it to an MCP sampling/createMessage request
3. The MCP client processes the request (invoking its LLM)
4. The result is converted back to an Anthropic Messages API response

Supported Conversions

Tech Stack

• Rust (2024 edition)
• rmcp — MCP protocol implementation
• axum — HTTP framework
• tokio — Async runtime
• serde / serde_json — Serialization

中文

概述

sampling2api 是一个用 Rust 编写的桥接工具，它将 MCP（Model Context Protocol）客户端的 Sampling（采样） 能力暴露为标准的 Anthropic Messages API（POST /v1/messages）。

这使得任何已经对接 Anthropic API 的外部服务或工具，都能无缝使用 MCP 客户端提供的 AI 能力——无需配置外部 API 密钥或提供商信息。

动机

在 MCP 生态中，Sampling 允许服务器向客户端请求 LLM 补全。然而，大多数现有工具和库是基于主流 HTTP API（如 Anthropic）构建的。sampling2api 弥合了这一鸿沟：它通过 HTTP 接收标准 Anthropic Messages API 请求，并将其转发为 MCP sampling/createMessage 调用发送给已连接的客户端。

特性

• 兼容 Anthropic Messages API — POST /v1/messages 端点，支持 JSON 和流式（SSE）响应
• 两种传输模式：
  • Stdio — 通过 stdin/stdout 连接 MCP 客户端（适合子进程方式）
  • Streamable HTTP — 通过 HTTP 连接 MCP 客户端（适合远程或多客户端场景）
• 工具调用支持 — 完整的工具调用、工具结果和多轮工具循环
• 图像支持 — 支持 base64 图像透传，以及 URL 图像下载后转为 base64
• 多会话路由 — HTTP 模式下多个 MCP 客户端可同时连接，通过 x-mcp-session-id 头进行路由
• 健康检查端点 — GET /health

安装

# 克隆仓库
git clone https://github.com/anthropics/sampling2api.git
cd sampling2api

# 使用 Cargo 构建
cargo build --release

编译产物位于 target/release/sampling2api。

使用方法

Stdio 模式

通过 stdin/stdout 连接 MCP 客户端，并在本地 HTTP 端口暴露 API：

sampling2api stdio --listen 127.0.0.1:38080

MCP 客户端将 sampling2api 作为子进程启动（或反向亦可）。连接成功后，向 http://127.0.0.1:38080/v1/messages 发送请求即可。

Streamable HTTP 模式

作为 HTTP 服务器运行，同时接受 MCP 客户端连接和 API 请求：

sampling2api http --listen 127.0.0.1:38080 --mcp-path /mcp

• MCP 客户端通过 Streamable HTTP 传输连接到 http://127.0.0.1:38080/mcp
• API 消费者向 http://127.0.0.1:38080/v1/messages 发送请求

当多个 MCP 客户端连接时，使用 x-mcp-session-id 请求头将请求路由到特定会话。

API 参考

POST /v1/messages

接受标准 Anthropic Messages API 请求体：

{
  "model": "claude-sonnet-4-0",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Hello, world!" }
  ],
  "stream": false
}

• 设置 "stream": true 获取 SSE 流式响应
• 设置 "stream": false（或省略）获取单次 JSON 响应
• model 字段作为模型偏好提示传递给 MCP 客户端

请求头：

GET /health

返回 ok，可用于就绪和存活探针。

架构

┌──────────────┐         ┌──────────────────┐         ┌────────────┐
│  API 消费者   │  HTTP    │   sampling2api   │   MCP   │ MCP 客户端  │
│  (如应用程序) │────────▶│                  │────────▶│ (含 LLM)   │
│              │◀────────│  /v1/messages     │◀────────│            │
└──────────────┘  JSON/  └──────────────────┘ sampling └────────────┘
                   SSE          桥接层         /createMessage

1. API 消费者向 /v1/messages 发送 Anthropic 格式的请求
2. sampling2api 将其转换为 MCP sampling/createMessage 请求
3. MCP 客户端处理请求（调用其 LLM）
4. 结果被转换回 Anthropic Messages API 响应格式

转换支持表

技术栈

• Rust（2024 edition）
• rmcp — MCP 协议实现
• axum — HTTP 框架
• tokio — 异步运行时
• serde / serde_json — 序列化