> For the complete documentation index, see [llms.txt](https://k4k3ru.gitbook.io/k4k3ru-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k4k3ru.gitbook.io/k4k3ru-docs/mcp.md).

# MCP

K4K3RU provides a public Model Context Protocol (MCP) server for AI agents and MCP-compatible clients. Use it to discover supported market venues and symbols inspect available credit products, and retrieve BBO, OrderBook, Spread and Carry evaluations through MCP tools.

## Endpoint

Connect to the MCP Streamable HTTP endpoint:

```
https://mcp.k4k3ru.com/
```

The server is stateless and returns JSON responses.

## Authentication

The MCP endpoint requires an OAuth Bearer token. MCP clients that support OAuth discovery can obtain the authorization-server details from the protected-resource metadata advertised by the server.

Protected-resource metadata is available at:

```
https://mcp.k4k3ru.com/.well-known/oauth-protected-resource
```

Requests without a valid Bearer token receive `401 Unauthorized`. A temporary OAuth introspection failure returns `503 Service Unavailable`.

## Connect from ChatGPT

Use a ChatGPT account with Developer mode enabled. Availability depends on your account and workspace policy; a workspace administrator may need to enable access.

1. In ChatGPT settings, enable **Developer mode** (currently under **Security and login**).
2. Open **Plugins**, select the plus button, and create an MCP connection named **K4K3RU**.
3. Enter `https://mcp.k4k3ru.com/` as the server URL and use OAuth authentication when prompted. Use the root URL exactly as shown; do not append `/mcp`.
4. Complete the K4K3RU sign-in and authorization flow described below.
5. Review the discovered tools, start a new conversation, and select the K4K3RU connection from the tools menu.

If updated tools are missing, refresh the connection's metadata and start a new conversation. Menu labels may change; see the [official OpenAI connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt) for the current interface.

## Connect from Claude Code

With Claude Code installed, register the HTTP server in your terminal:

```sh
claude mcp add --transport http --scope user k4k3ru https://mcp.k4k3ru.com/
```

`--scope user` makes the connection available across your projects. Start Claude Code, enter `/mcp`, select `k4k3ru`, and choose its authentication action. Complete the browser sign-in and authorization flow below, then return to Claude Code and check the connection status with `/mcp`.

To inspect the saved configuration from your terminal:

```sh
claude mcp get k4k3ru
```

See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp) for installation scopes and OAuth troubleshooting.

## Complete K4K3RU Sign-In

The MCP client opens K4K3RU's OAuth authorization page in your browser. Sign in using an email address you can access, enter the emailed one-time code on that page, and approve the requested access. Return to the MCP client after the redirect completes. Enter the code in the sign-in page, not in the conversation. The client manages the resulting OAuth tokens; you do not need to paste a Bearer token into chat or a command.

If authentication does not complete, check the client's connection status and restart its authentication flow. An unauthenticated request returning `401` is expected; persistent `401` after sign-in requires reconnecting or investigating the authentication error. A `503` indicates a temporary service issue.

## Verify the Connection

Start with a coverage query:

> Use K4K3RU to list the available market-data venues and their status.

Confirm that the client invokes `market_hub_list_venues` and displays its result. Then try a market evaluation:

> Use K4K3RU to get the latest BTC/USDC spot best bid and offer.

For Carry:

> Use K4K3RU to search BTC/USDC Funding carry candidates for 0.1 BTC over 1440 minutes with a minimum estimated Funding of 0 bps.

The expected tools are `market_hub_get_bbo` and `market_hub_search_carry`, respectively. An empty candidate list is a valid result, not a connection failure. Market values depend on available data. These tools retrieve single evaluations; they do not place orders or continuously monitor positions.

## Direct Connections and Directory Listings

The setup above adds the MCP server directly. It does not require K4K3RU to be listed in a public directory, but remains subject to your client's account and workspace permissions. Public directory publication is a separate submission and review process; see the [OpenAI submission guide](https://developers.openai.com/plugins/deploy/submission) and [Claude directory submission guide](https://claude.com/docs/connectors/building/submission). A direct connection does not imply approval or endorsement by either provider.

## Available Tools

### `market_hub_list_venues`

Lists configured market-data venues and their current status. The tool takes no arguments.

The result contains each venue's name, status, and status update time.

### `market_hub_list_symbols`

Lists enabled canonical market symbols. Omit `venues` to query all enabled venues, or provide one or more venue queries.

| Input field            | Type         | Required | Description                                                                            |
| ---------------------- | ------------ | -------- | -------------------------------------------------------------------------------------- |
| `venues`               | array        | No       | Venue queries. Omit to list symbols for all enabled venues.                            |
| `venues[].name`        | string       | Yes      | `binance`, `btse`, `bybit`, `coinbase`, `dydx`, `hyperliquid`, `okx`, or `uniswap-v4`. |
| `venues[].page`        | integer      | No       | One-based page. Zero selects page 1.                                                   |
| `venues[].limit`       | integer      | No       | Maximum symbols. Zero selects 100; maximum 500.                                        |
| `venues[].marketTypes` | string array | No       | Filter by `spot` or `perp`.                                                            |

Example arguments:

```json
{
  "venues": [
    {
      "name": "binance",
      "marketTypes": ["spot"],
      "page": 1,
      "limit": 100
    }
  ]
}
```

The result groups canonical symbols and their available market types by venue and includes pagination metadata.

### `account_app_list_products`

Lists active K4K3RU credit products.

| Input field | Type    | Required | Description                                                                |
| ----------- | ------- | -------- | -------------------------------------------------------------------------- |
| `page`      | integer | No       | One-based page. Zero selects page 1; each page contains up to 20 products. |

The result includes product pricing, credit and bonus ticks, expiry, purchase limit, description, metadata, and pagination fields.

## Market Evaluations

The following read-only tools use the same parameter names and result fields as the corresponding Gateway RPCs. They return a single evaluation, not a live subscription. Availability depends on deployment of the updated MCP server.

| Tool                        | Gateway RPC               | Required arguments                                                 |
| --------------------------- | ------------------------- | ------------------------------------------------------------------ |
| `market_hub_get_bbo`        | `MarketHub.BBO.Get`       | `symbol`, `marketType`                                             |
| `market_hub_get_order_book` | `MarketHub.OrderBook.Get` | `symbol`, `marketType`                                             |
| `market_hub_get_spread`     | `MarketHub.Spread.Get`    | `symbol`, `baseAsset`, `quantity`                                  |
| `market_hub_search_carry`   | `MarketHub.Carry.Search`  | `symbol`, `baseAsset`, `quantity`, `holdingPeriodMinutes`          |
| `market_hub_get_carry`      | `MarketHub.Carry.Get`     | `symbol`, `baseAsset`, `quantity`, `holdingPeriodMinutes`, `route` |

`assetClass` defaults to `crypto`; `marketType` is `spot` or `perp`. Quantities and bps thresholds are decimal strings. Optional `sourceFilter` is supported by BBO, OrderBook, Spread and Carry Search. OrderBook `depth` defaults to 3 (maximum 20). Spread `minimumGrossSpreadBps` defaults to `"0"` and supports all four spot/perp route families. Gross spread excludes fees, Funding, borrowing, gas and transfer costs.

Carry Search example arguments:

```json
{
  "symbol": "BTC/USDC",
  "baseAsset": "BTC",
  "quantity": "0.1",
  "holdingPeriodMinutes": 1440,
  "minimumEstimatedFundingBps": "0",
  "routeFamilies": ["spot-perp", "perp-spot", "perp-perp"]
}
```

The holding period must be 1–43200 minutes; 1440 compares a 24-hour estimate. The minimum Funding threshold defaults to `"0"`; a negative threshold includes estimated payment routes. Copy an eligible candidate's `route` into Get:

```json
{
  "symbol": "BTC/USDC",
  "baseAsset": "BTC",
  "quantity": "0.1",
  "holdingPeriodMinutes": 1440,
  "route": {
    "buy": {"venue": "binance", "marketType": "perp"},
    "sell": {"venue": "hyperliquid", "marketType": "perp"}
  }
}
```

Keep `chain`, `network` and `poolId` for pool legs. Fixed Carry Get does not accept search thresholds, route families or source filters. Its result preserves `routeId`, `evaluationKey`, `evaluationId`, `status`, `availability` (including `observedAt`, `validUntil` and reasons), and optional evaluation values. Missing or expired values must not be treated as zero or currently actionable data.

Results retain SDK wire names: for example `s` is the canonical symbol, `q` the base quantity, `hpm` the holding period and `er` the eligible routes. Carry `fundingEstimate` and `entrySpread` remain separate. Funding assumes constant rates and Mark Prices, and annualization is not margin ROI. `assessment` reports costs and execution checks that have not been evaluated; `perp-spot` includes an unevaluated Spot borrowing requirement.

These tools require the existing MCP OAuth Bearer authentication. Gateway forwarding follows the existing MCP public-method policy: these five RPCs are sent without an account API signature. An MCP Bearer token does not itself activate Carry's 60/minute account quota; public Gateway limits still apply. No Agent `state.json` or `auth.json` is read by the MCP service.

## Architecture Boundary

The MCP server translates tool calls into K4K3RU Gateway API operations. It does not expose venue-specific APIs or provide direct access to CRM, Payment, or Market Hub.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://k4k3ru.gitbook.io/k4k3ru-docs/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.