Setup

Requirements

• A JokerPrice API key from Data & API.
• Hosted server: an MCP client that connects to remote (Streamable HTTP) servers and can send a request header. Nothing to install.
• Local server, as an alternative: Node.js 20 or newer and the mcp/ folder of the JokerPrice repository, with npm install run once inside it.

1. Create an API key

Sign in, open Data & API and create a key named after the assistant, such as claude. Copy it; it is shown once.

Start free trial

2. Connect to the hosted server

Point your client at the endpoint below and send the key in the Authorization header. The server speaks the Streamable HTTP transport and answers each request with JSON; nothing runs on your machine.

URL: https://jokerprice.com/mcp
Authorization: Bearer ss_your_key_here

In Claude Code, add it with one command:

claude mcp add --transport http jokerprice https://jokerprice.com/mcp --header "Authorization: Bearer ss_your_key_here"

For Claude Desktop, Codex and Cursor, see step 4. Each tool call counts as one request against the key's limits; connecting and listing the tools do not.

3. Test it

Any HTTP client can call the endpoint with JSON-RPC 2.0. List the tools, then call one:

curl https://jokerprice.com/mcp \
  -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://jokerprice.com/mcp \
  -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_market","arguments":{"slug":"riyadh"}}}'

A tool result arrives as JSON text in result.content; a failure sets result.isError and explains what to fix. A 401 response means the key is missing, wrong or revoked.

4. Connect a client

• Claude Desktop and Claude Code
• Codex
• Cursor and other clients

Cursor and other clients

In Cursor, add the hosted server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) and enable it under Cursor Settings → MCP. Other clients that connect to remote servers take the same URL and header.

{
  "mcpServers": {
    "jokerprice": {
      "url": "https://jokerprice.com/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_key_here"
      }
    }
  }
}

To run the local server instead, most clients accept this shape, with the absolute path to index.mjs:

{
  "mcpServers": {
    "jokerprice": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp/index.mjs"
      ],
      "env": {
        "JOKERPRICE_API_KEY": "ss_your_key_here"
      }
    }
  }
}

Run it locally instead

The same tools also run on your own machine over stdio, from the mcp/ folder of the JokerPrice repository. Clients start it as a command and pass the key as an environment variable. Use it with clients that only start local servers, or to work against a local development server.

Install the local server

cd mcp
npm install
pwd   # note this folder: clients need the absolute path to index.mjs

Local server configuration

Clients pass these as environment variables when they start the server. Set JOKERPRICE_BASE_URL=http://localhost:4173 to use a local development server.

Test the local server

The MCP Inspector starts the server and lets you call each tool by hand before you connect an assistant.

JOKERPRICE_API_KEY=ss_your_key_here npx @modelcontextprotocol/inspector node /absolute/path/to/mcp/index.mjs

Call list_markets. A list of destinations means the key and network work.

Troubleshooting

• 401 when connecting (hosted): the client did not send Authorization: Bearer ss_…, or the key is wrong or revoked. Check the header in the client's configuration, or create a new key.
• 403 (hosted): the request came from a web page on another site. Browser pages other than jokerprice.com cannot call the endpoint; connect from an MCP client instead.
• 405 on GET (hosted): expected. The server answers POST requests with JSON and does not open event streams; clients carry on without one.
• "JOKERPRICE_API_KEY is not set" (local): the client did not pass the environment variable. Check the env block.
• "does not look like a JokerPrice key" (local): the key must be ss_ followed by 40 hex characters.
• "JokerPrice rejected the API key" (local): the key is wrong or revoked; create a new one.
• Rate limit reached: the per-minute or daily limit was reached; the tool error says how long to wait.
• Tools do not appear (local): use an absolute path to index.mjs, confirm node --version is 20+, and restart the client.