# Documentation MCP Server

CoinsSend exposes a read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for AI coding agents and developer tools. It serves the same reviewed public documentation and OpenAPI contract as this site. It cannot create invoices, wallets, withdrawals, or call any other business endpoint.

## Connect remotely

Use this Streamable HTTP endpoint in an MCP client that supports protocol revision `2025-11-25` or an older revision negotiated by the server:

```text
https://api.coinssend.com/v1/docs/mcp
```

No API key is required because the server exposes public documentation only. Requests are rate-limited. A client that requires only the newer stateless `2026-07-28` protocol revision will need a future server upgrade.

For Codex, register the remote server with:

```bash
codex mcp add coinssend-docs --url https://api.coinssend.com/v1/docs/mcp
```

MCP client configuration formats differ. In clients that accept a URL-based server entry, the equivalent shape is:

```json
{
  "mcpServers": {
    "coinssend-docs": {
      "url": "https://api.coinssend.com/v1/docs/mcp"
    }
  }
}
```

## Run locally

From the API Application repository, install Composer dependencies and start the registered local server:

```bash
php artisan mcp:start docs
```

The local transport exposes the same resources and tools as the HTTP endpoint.

## Resources

| URI | Media type | Contents |
|---|---|---|
| `docs://manifest` | `application/json` | Ordered allowlist of public pages and machine-readable resources |
| `docs://openapi` | `application/vnd.oai.openapi+json;version=3.1` | Canonical public OpenAPI 3.1 contract |
| `docs://signature-test-vectors` | `application/json` | Executable fixtures for PHP-compatible request canonicalization and signatures |

Private maintainer notes are not present in these resources and cannot be read through page tools.

## Tools

| Tool | Purpose |
|---|---|
| `search_docs` | Deterministic lexical search with at most eight bounded results |
| `get_docs_page` | Read one exact public Markdown path returned by the manifest or search |
| `get_openapi_operation` | Retrieve an operation by its stable `operationId` |
| `get_openapi_schema` | Retrieve a named schema from `components.schemas` |

All tools are annotated read-only, idempotent, and closed-world. They read local, allowlisted files only; they do not call OpenAI or the CoinsSend business API.

## Agent safety guidance

- Use OpenAPI operations and schemas for request and response structure; use prose pages for workflow and operational guidance.
- Treat MCP output as documentation, not as approval to move funds or perform a production action.
- Do not infer idempotency. In particular, invoice creation, static-wallet creation, and withdrawal creation do not accept an `Idempotency-Key` contract.
- Validate the current live coin and network catalog before constructing a transaction; supported assets and fees are runtime data.
- Keep merchant API keys outside prompts, logs, source control, and MCP arguments.

For clients without MCP support, use the generated [`llms.txt`](llms.txt) index or the canonical [`openapi.json`](openapi.json) directly.