# MCP Server

Connect Claude Desktop, Cursor or any MCP client to the samreshuuu connector catalog and Python sandbox.

## What it is

The server speaks Model Context Protocol (version 2025-06-18) over Streamable HTTP, mounted at /mcp/ with server name samreshuuu-coworker. The same toolset the chat assistant uses is exposed to external clients: a catalog of ~90 integrations, a Python REPL sandbox, and access to user memory and the knowledge base (Drive).

## Connect a client

Drop the snippet below into claude_desktop_config.json, the Cursor mcp.json, or your client's equivalent. The same URL and a ready-made config are also surfaced in your project settings.

```json
{
  "mcpServers": {
    "samreshuuu-coworker": {
      "url": "https://api.samreshuuu.com/mcp/",
      "headers": {
        "Authorization": "Bearer sk-org-xxxxxxxxxxxx"
      }
    }
  }
}
```

[Create an API key in settings →](/settings/api-keys)

## Authentication

Every request needs an Authorization: Bearer sk-org-… header. Keys are issued in Settings → API keys, carry scopes (read:tools, write:tools, read:data, admin, chat) and an expiry. The user_id and org_id are derived from the key — no separate X-Org-Id header is needed.

## Public info endpoint

GET /api/v1/mcp/info returns the URL, server name, protocol version, supported scopes, and an example config. It is unauthenticated — handy for generating client snippets.

```json
{
  "url": "https://api.samreshuuu.com/mcp/",
  "server_name": "samreshuuu-coworker",
  "protocol_version": "2025-06-18",
  "supported_scopes": ["read:tools", "write:tools", "read:data", "admin", "chat"],
  "example_config": { "mcpServers": { "samreshuuu-coworker": { "url": "...", "headers": { "Authorization": "Bearer sk-org-<your-key>" } } } }
}
```

## Available tools

The same tools the chat assistant uses. user_id and org_id come from the bearer key, so every call runs in the key owner's context.

| Tool | Purpose |
| --- | --- |
| `list_services` | Connector catalog: name + one-line summary per service. Handshake-sized (~2–5 KB) — every session starts here. |
| `describe_service` | Full passport for one service: modules, common recipes, rate limits, field hints, pagination hints, plus version/ttl for client-side caching. |
| `connector_execute` | Single executor for any connector call. REST: module + HTTP method + path + body/query. RPC (bitrix24, onec, …): leave path empty and pass the RPC method name in method. |
| `repl_execute` | Execute Python in the user's sandbox. Connector credentials are auto-injected as env vars (WILDBERRIES_API_KEY, …). Requested skills mount at `/mnt/skills/<id>/scripts/`. |
| `read_memory` | Read the user's persistent memory store: read a single file, list by prefix with pagination, or read_many to batch up to 50 paths. |

Typical call sequence:

```bash
→ list_services()
→ describe_service("wildberries")
→ connector_execute(
    service="wildberries",
    module="statistics",
    method="GET",
    path="/api/v1/supplier/orders",
    query={"dateFrom": "2026-04-15"}
  )
→ repl_execute(
    code="from wb_analytics import abc_classify; ...",
    skills=["wb_analytics"]
  )
```

## Skill resources

Every enabled organization skill is exposed as an MCP resource at `skill://{skill_id}`. The body is the skill's system_prompt with a hint on how to call connector_execute against the bound service. The server populates resources for all enabled skills on the first authenticated request, so resources/list enumerates them all.

## Errors

Tool failures arrive as a standard MCP ToolError whose body is JSON with code, message, retryable, and optional hint and details. Common codes:

```json
{
  "code": "UNKNOWN_SERVICE",
  "message": "Connector 'foo' not registered",
  "retryable": false,
  "hint": "Known services: wildberries, ozon, telegram, ..."
}
```

| Field | Description |
| --- | --- |
| `UNAUTHENTICATED` | Missing or invalid bearer key. Check the sk-org- prefix and that the key has not expired. |
| `UNKNOWN_SERVICE` | The connector name is not registered. The hint field lists known services. |
| `INVALID_ARG` | Invalid argument: unknown module/method, Pydantic validation error, or contract violation. Details land in the details field. |
| `NOT_FOUND` | Resource not found (for example, a memory file at the requested path). |
| `UPSTREAM_ERROR` | An upstream service returned an error. The retryable flag indicates whether the call is worth retrying. |

**Quick Links**

- [Settings → API keys & MCP server](/settings/api-keys)
- [Authentication — Bearer tokens and organization context](/docs/authentication)