Setup

Setup

This page takes you from nothing to a working MCP connection: obtain the access token, verify it with a plain HTTP call, then wire it into your AI assistant.

What you need

You do not need a Groove backoffice login, a security key, or any firewall change: the MCP is a normal outbound HTTPS call from your machine or CI to the Groove gateway.

The gateway routes

The gateway exposes two MCP routes. Only the first one is for you — the second is how Groove issues your token.

Step 1 — Get your access token

Ask your Groove account manager for an MCP access token and the gateway base URL for the environment you are integrating against.

The token is a long opaque string. It is constant and does not expire — you set it once in your client and there is nothing to renew. It stays valid until Groove rotates the signing key.

Step 2 — Verify it with a plain HTTP call

Before touching any client config, confirm the token works. This lists the available tools:

curl -s -X POST https://<groove-gateway>/mcp \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A healthy response lists 9 tools: list_tools, get_server_info, get_endpoint, list_endpoints, search_docs, sign_request, verify_signature, generate_snippet, generate_integration.

A second sanity check — ask it for the reverse endpoint catalogue:

curl -s -X POST https://<groove-gateway>/mcp \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_endpoints","arguments":{"integration":"reverse"}}}'

You should get 19 endpoints, grouped by category — the Transaction Flow operations, Game Launch, the Free Round Bonus calls, and the reference pages. If that comes back, your token and URL are both correct.

Step 3 — Connect your AI assistant

Use the HTTP (Streamable HTTP) transport, point it at https://<groove-gateway>/mcp, and pass the token in the Authorization header.

Claude Code (CLI)

claude mcp add --transport http groove https://<groove-gateway>/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

Cursor, VS Code, and generic MCP clients (mcp.json)

{
  "mcpServers": {
    "groove": {
      "url": "https://<groove-gateway>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      }
    }
  }
}

After adding the server, restart or reload your client — it should list the 9 tools. Ask it something simple to confirm, for example “Using the Groove MCP, list the reverse integration transaction endpoints.”

Calling the MCP directly over HTTP

You do not need an AI client. /mcp is plain JSON-RPC 2.0 over HTTPS, so you can drive it from a script, from your test suite, or from a build step.

Envelope:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool name>",
    "arguments": { }
  }
}

Required headers:

Example — verify an inbound signature on a getbalance request:

curl -s -X POST https://<groove-gateway>/mcp \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
        "name":"verify_signature",
        "arguments":{
          "integration":"reverse",
          "pathAndQuery":"/groove?request=getbalance&gamesessionid=123&accountid=456",
          "key":"<your base64 Access Key Value>",
          "signature":"<the base64 signature from the Authorization header>"
        }}}'

The result is returned as text content — valid, or invalid signature (401).

Response and error codes

A tool-level failure (an unknown endpoint name, a malformed query) still returns HTTP 200 with isError: true and an explanatory message in the result content — that is normal MCP behaviour, not a transport failure.

Troubleshooting

Tools Reference

Tools Reference

The MCP server exposes 9 tools. Your AI assistant picks them automatically from your prompt, but they are documented here in full so you can call them directly over HTTP or check exactly what your assistant is doing.

Every argument below goes in params.arguments of a tools/call request — see Calling the MCP directly over HTTP.

Tool summary

Documentation tools

list_endpoints

Lists every documented endpoint, grouped by integration and category.

{ "name": "list_endpoints", "arguments": { "integration": "reverse" } }

Returns the 19 reverse-integration entries:

get_endpoint

Returns the full structured spec for one endpoint: request parameters, response fields, status codes, signature scheme and authentication.

{ "name": "get_endpoint", "arguments": { "integration": "reverse", "name": "Wager" } }

Returns JSON — the endpoint’s method, path, category, summary, every documented parameter with its type and whether it is required, the success response shape, and the applicable status codes.

search_docs

Free-text search over endpoint names, summaries and categories.

{ "name": "search_docs", "arguments": { "query": "free round", "integration": "reverse" } }

Signature tools

Both signature tools implement the reverse scheme exactly as described in Signature Validation:

Signature = base64_encode(HMACSHA256(Path-And-Query, base64_decode(Access Key Value)))
Header    = Authorization: HMAC-SHA256 Signature={Signature}

Pass the Access Key Value as key — the tool performs the base64 decode for you.

sign_request

Computes the signature and returns the ready-to-send header.

{
  "name": "sign_request",
  "arguments": {
    "integration": "reverse",
    "pathAndQuery": "/groove?request=getbalance&gamesessionid=123&accountid=456",
    "key": "<your Access Key Value>"
  }
}

Result:

Authorization: HMAC-SHA256 Signature=<base64 signature>

verify_signature

The request checker: confirms a signature matches the request. Use it when a signature is being rejected and you need to know whether the fault is yours or the sender’s.

Result is valid, or invalid signature (401).

Code generation tools

generate_snippet

A single runnable example for one endpoint, with the signing or verification step shown explicitly.

{
  "name": "generate_snippet",
  "arguments": { "integration": "reverse", "name": "Wager", "language": "python" }
}

generate_integration

Generates a complete, startable project — not a snippet. You get the files of a working skeleton:

• A real /groove entry point wired for all 7 reverse transaction operations: getaccount, getbalance, wager, result, rollback, jackpot, wagerAndResult.
• Inbound Authorization HMAC verification, implemented against the documented scheme.
• The documented success responses and the full error catalogue — HTTP 200 with the status in the body, as this API specifies.
• One wallet seam per operation family: the small set of files you fill in with your own logic, routed per brand.

{ "name": "generate_integration", "arguments": { "integration": "reverse", "language": "go" } }

Returns a JSON list of files, each with a path, content, and an action:

That split means you can re-run generate_integration after a docs update to refresh the plumbing without losing your own code.

Server tools

list_tools

Returns every registered tool with its description and full JSON input schema. No arguments. Useful for confirming your client is talking to the server you expect.

get_server_info

Reports the server’s identity and the size of its loaded catalogue. No arguments.

Use it as a liveness check: a successful response means your token is valid and the server is serving.

Example Workflows

Example Workflows

Once the MCP is connected, you work with it in plain language — your assistant chooses the tools. These are the requests that come up most often during a reverse integration, plus the raw HTTP equivalents for when you want to script them.

Prompts that work well

Exploring the API

• “List the reverse-integration transaction endpoints.”
• “Show me the full spec for the reverse Wager endpoint — every parameter and status code.”
• “What does the reverse integration require me to store to handle a later Rollback?”
• “Search the reverse docs for anything about free rounds.”

Signatures

• “Compute the Authorization header for /groove?request=getbalance&gamesessionid=123&accountid=456 with access key <key>, reverse scheme.”
• “This request came in with signature <sig> — is it valid for path-and-query <path> with key <key>?”
• “My signature check keeps failing on Wager. Show me exactly what string should be hashed.”

Writing code

• “Generate a Python snippet for the reverse Result endpoint, including the signature verification.”
• “Generate a full Go project for the reverse integration and write the files into ./groove-integration.”
• “Regenerate the reverse TypeScript blueprint and tell me which files are safe to overwrite.”

Workflow 1 — Look up an endpoint before implementing it

Ask: “Show me the full spec for the reverse Wager endpoint.”

Your assistant calls:

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

You get the documented request parameters, the success response shape, and the status codes — the same content as the Wager page, but structured, so your assistant can generate matching code from it directly.

Follow up with “now generate the handler in Java” and it chains straight into generate_snippet.

Workflow 2 — Debug a failing signature

This is the fastest use of the MCP. When a signature is rejected, the question is always whose side is wrong — and verify_signature answers it against a reference implementation.

Give your assistant the exact path-and-query you received, the signature from the Authorization header, and your access key:

curl -s -X POST https://<groove-gateway>/mcp \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"verify_signature",
        "arguments":{
          "integration":"reverse",
          "pathAndQuery":"/groove?request=wager&gamesessionid=123&accountid=456&transactionid=789&betamount=1.00",
          "key":"<your Access Key Value>",
          "signature":"<signature from the Authorization header>"
        }}}'

Reading the result:

Then have it compute the expected value for comparison:

{
  "name": "sign_request",
  "arguments": {
    "integration": "reverse",
    "pathAndQuery": "/groove?request=wager&gamesessionid=123&accountid=456&transactionid=789&betamount=1.00",
    "key": "<your Access Key Value>"
  }
}

Diffing that against what your code produces isolates the fault in one step.

Workflow 3 — Generate a working skeleton

Ask: “Generate a full Go project for the reverse integration and write the files into ./groove-integration.”

Your assistant calls generate_integration and writes out the returned files:

{
  "name": "generate_integration",
  "arguments": { "integration": "reverse", "language": "go" }
}

What you get is startable, not illustrative — a /groove entry point handling all seven transaction operations, inbound signature verification, and the documented response and error catalogue already wired up.

Then do the work that is actually yours:

1. Open the create-if-absent files — these are the wallet seams, one per operation family.
2. Implement your balance, bet, win, and rollback logic behind them.
3. Fill in your access key and Groove endpoint configuration.
4. Run it, and use verify_signature (Workflow 2) to confirm the inbound checks pass.

The overwrite files are protocol plumbing. Leave them alone — re-running generate_integration after a docs update refreshes them without touching your seams.

Workflow 4 — Keep implementation and docs in step

Because the MCP serves the same specs published on this site, it is worth re-asking after any Groove docs update:

• “Compare the reverse Wager spec to my handler in wager.go — am I missing any parameter?”
• “List every status code the reverse Rollback endpoint can return, and check my switch statement covers them.”
• “Regenerate the reverse Go blueprint and show me a diff of the overwrite files.”

This turns the certification checklist into something your assistant can verify against the source of truth rather than against your memory of it.

Getting help