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