Setup

Setup

Prerequisites

Endpoint

POST https://<sinatra-gateway>/mcp

Required headers

The body is a standard JSON-RPC 2.0 message. Responses are returned as application/json.

Option 1 — Connect an AI client

This is the normal way to use the MCP. Configure it once and your assistant handles the protocol for you.

Claude Code

claude mcp add --transport http groove https://<sinatra-gateway>/mcp \
  --header "Authorization: Bearer <your-access-key>"

Cursor and other MCP clients

Add the server to your client’s mcp.json:

{
  "mcpServers": {
    "groove": {
      "url": "https://<sinatra-gateway>/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-key>"
      }
    }
  }
}

Once connected, your client lists 9 tools (see Available Tools). You can then simply ask, for example:

• “Show me the spec for the Wager endpoint.”
• “Sign this request with key X: request=getaccount&…”
• “Is this X-Groove-Signature valid for this request?”
• “Generate a Python snippet for the Result endpoint.”
• “Generate a full Go project for the Groove integration.”

Verify the connection

Ask your assistant to call get_server_info. A working connection reports the server name (groove-mcp), its version, and the number of endpoints it has loaded.

Option 2 — Call it directly over HTTP

The MCP is an ordinary HTTPS API, so you can use it from curl, Postman, or your own code — useful for a quick smoke test or for scripting signature checks in CI.

List the available tools

curl --location 'https://<sinatra-gateway>/mcp' \
--header 'Authorization: Bearer <your-access-key>' \
--header 'Content-Type: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}'

Call a tool

Every tool is invoked with method: "tools/call", the tool name, and its arguments:

curl --location 'https://<sinatra-gateway>/mcp' \
--header 'Authorization: Bearer <your-access-key>' \
--header 'Content-Type: application/json' \
--data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sign_request",
    "arguments": {
      "integration": "regular",
      "query": "request=getaccount&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&apiversion=1.2",
      "key": "test_key"
    }
  }
}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "X-Groove-Signature: be426d042cd71743970779cd6ee7881d71d1f0eb769cbe14a0081c29c8ef2a09"
      }
    ],
    "isError": false
  }
}

Troubleshooting

Available Tools

Available Tools

The Groove MCP server exposes 9 tools. All of them are read-only — they answer from the embedded documentation snapshot and never call a backend or change any state.

Every tool is called with method: "tools/call" — see Setup for the request format.

Discovery

list_tools

List all available MCP tools with their descriptions and input schemas.

Arguments: none.

Returns: total_tools and a tools array, each entry with name, description and input_schema.

get_server_info

Report this MCP server’s name, version, and how many endpoints it serves. Useful as a connectivity check.

Arguments: none.

Returns: the server identity — groove-mcp, its version, and the number of endpoints loaded.

Documentation lookup

list_endpoints

List every documented endpoint, grouped by category.

Returns: a grouped listing — endpoint name, HTTP method and one-line summary per category.

37 endpoint(s):

[regular] Transaction API
  - GetAccount (GET) — Validate the player session and return account details.
  - GetBalance (GET) — Return the player's current balance.
  ...

get_endpoint

Return the full spec — parameters, responses, error codes, signature and authentication — for one endpoint.

Returns: the endpoint object, including name, category, summary, method, path, auth, params, responses, errorCodes, signature, and the sourceUrl of the documentation page it was taken from.

Example call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_endpoint",
    "arguments": { "integration": "regular", "name": "Wager" }
  }
}

search_docs

Search endpoints by name, summary or category.

Returns: a match list of [integration / category] Name — Summary.

Signatures

sign_request

Compute the X-Groove-Signature for a request — HMAC-SHA256 over the sorted parameter values, hex-encoded.

Returns: the ready-to-use header line.

Example call:

{
  "name": "sign_request",
  "arguments": {
    "integration": "regular",
    "query": "request=getaccount&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&apiversion=1.2",
    "key": "test_key"
  }
}

Result:

X-Groove-Signature: be426d042cd71743970779cd6ee7881d71d1f0eb769cbe14a0081c29c8ef2a09

verify_signature

Check whether a signature is valid for a request — the same check Groove performs. Use it to debug a rejected request.

Returns: valid, or the failure the caller would have seen — invalid signature (code 1001).

See Signature Validation for how the signature is built.

Code generation

generate_snippet

Return a runnable code example for one endpoint, with the signing or verification step shown explicitly rather than hidden in a helper.

Returns: the snippet as text.

generate_integration

Generate a ready-to-run integration blueprint: the files of a startable project — a real /groove entry point, the documented success responses and error catalogue, and one wallet seam per operation family for you to fill in, routed per brand.

It emits the full core transaction flow; individual endpoints cannot be selected.

Returns: a JSON project — integration, language, optional notes, and a files array:

{
  "integration": "regular",
  "language": "go",
  "files": [
    { "path": "go.mod",        "action": "overwrite",        "content": "..." },
    { "path": "main.go",       "action": "overwrite",        "content": "..." },
    { "path": "app/wallet.go", "action": "create-if-absent", "content": "..." }
  ]
}

The action tells you how to write each file: