What can you do with this server?

The nakama-mcp server provides an MCP interface to a Heroic Labs Nakama game backend, enabling AI models to interact with both the player-facing Client API and the admin Console API across ~180 operations. Discovery & General Execution * Search API actions (nakama_search_actions): Find any of the ~180 available Nakama operations by natural-language intent, returning action IDs, HTTP method/path, and parameter schemas * Execute any action (nakama_execute_action): Run any discovered operation by its action ID with support for path params, query params, and request body; supports auto-pagination to follow cursors and merge pages Player / Client API * Authenticate players (nakama_authenticate): Establish a player session via device, custom, or email authentication methods * Call server RPCs (nakama_call_rpc): Invoke registered runtime RPC functions, with optional HTTP key for unauthenticated calls * Write storage objects (nakama_write_storage_object): Create or update a storage object as the authenticated player, with permission and optimistic-concurrency control * Submit leaderboard scores (nakama_write_leaderboard_record): Post a score (with optional subscore and metadata) to a leaderboard as the authenticated player Admin / Console API * List/search player accounts (nakama_console_list_accounts): Browse or filter player accounts by user ID or username, with auto-pagination * Get a player account (nakama_console_get_account): Fetch full account details (profile, wallet, devices, linked logins) for a specific user ID * List storage objects (nakama_console_list_storage): Browse storage objects filtered by collection, key, and/or owner, with auto-pagination * Get server status (nakama_console_get_status): Retrieve node status and lightweight service metrics (CPU, memory, latency, presences) * Send notifications (nakama_send_notification): Deliver in-app notifications to a specific player with custom code, subject, and content * Ban/unban a player (nakama_ban_account, nakama_unban_account): Ban or remove a ban from a player account by user ID Diagnostics * Healthcheck (nakama_healthcheck): Probe both the client and console API surfaces, verify admin login, and get a per-surface reachability report Reliability Features * Auto-pagination on list endpoints (merges pages, reports __pages_fetched / __more_available) * Secret redaction: strips server keys, passwords, JWTs, and auth headers from error output before it reaches the model * Automatic console JWT management (auto-login and token refresh)

How do I use nakama-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nakama-mcp List the 10 most recent players whose username contains 'test'." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

nakama-mcp

by mlger

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

The nakama-mcp server provides an MCP interface to a Heroic Labs Nakama game backend, enabling AI models to interact with both the player-facing Client API and the admin Console API across ~180 operations.

Discovery & General Execution

Search API actions (nakama_search_actions): Find any of the ~180 available Nakama operations by natural-language intent, returning action IDs, HTTP method/path, and parameter schemas
Execute any action (nakama_execute_action): Run any discovered operation by its action ID with support for path params, query params, and request body; supports auto-pagination to follow cursors and merge pages

Player / Client API

Authenticate players (nakama_authenticate): Establish a player session via device, custom, or email authentication methods
Call server RPCs (nakama_call_rpc): Invoke registered runtime RPC functions, with optional HTTP key for unauthenticated calls
Write storage objects (nakama_write_storage_object): Create or update a storage object as the authenticated player, with permission and optimistic-concurrency control
Submit leaderboard scores (nakama_write_leaderboard_record): Post a score (with optional subscore and metadata) to a leaderboard as the authenticated player

Admin / Console API

List/search player accounts (nakama_console_list_accounts): Browse or filter player accounts by user ID or username, with auto-pagination
Get a player account (nakama_console_get_account): Fetch full account details (profile, wallet, devices, linked logins) for a specific user ID
List storage objects (nakama_console_list_storage): Browse storage objects filtered by collection, key, and/or owner, with auto-pagination
Get server status (nakama_console_get_status): Retrieve node status and lightweight service metrics (CPU, memory, latency, presences)
Send notifications (nakama_send_notification): Deliver in-app notifications to a specific player with custom code, subject, and content
Ban/unban a player (nakama_ban_account, nakama_unban_account): Ban or remove a ban from a player account by user ID

Diagnostics

Healthcheck (nakama_healthcheck): Probe both the client and console API surfaces, verify admin login, and get a per-surface reachability report

Reliability Features

Auto-pagination on list endpoints (merges pages, reports __pages_fetched / __more_available)
Secret redaction: strips server keys, passwords, JWTs, and auth headers from error output before it reaches the model
Automatic console JWT management (auto-login and token refresh)

nakama-mcp

License: Apache-2.0 Node >= 18

An MCP (Model Context Protocol) server for Heroic Labs Nakama. It lets Claude (or any MCP host) talk to a running Nakama instance across both of its HTTP APIs:

Client API (:7350) — player-facing: authentication, accounts, friends, groups, storage, leaderboards, tournaments, RPCs, …
Console API (:7351) — admin/operations: search players, inspect & edit storage, leaderboards, active matches, server status & metrics, …

Nakama exposes ~180 operations across the two surfaces, so this server uses a search + execute design instead of one tool per endpoint, plus a handful of promoted convenience tools for the most common jobs.

Tools

Tool	Read/Write	What it does
`nakama_search_actions`	read	Find operations by intent → returns action IDs, method/path, params.
`nakama_execute_action`	write	Run any operation by `action_id` with `path_params` / `query_params` / `body`.
`nakama_authenticate`	write	Establish a player session (device / custom / email) for client-API calls.
`nakama_call_rpc`	write	Call a registered runtime RPC (payload encoded the way the gateway expects).
`nakama_console_list_accounts`	read	List / search player accounts.
`nakama_console_get_account`	read	Fetch one player account by user ID.
`nakama_console_list_storage`	read	List storage objects (filter by collection / key / owner).
`nakama_console_get_status`	read	Node status and lightweight service metrics.
`nakama_healthcheck`	read	Probe client + console reachability and admin login.
`nakama_write_storage_object`	write	Write/update a storage object as the authenticated player.
`nakama_write_leaderboard_record`	write	Submit a score to a leaderboard as the authenticated player.
`nakama_send_notification`	write	Send an in-app notification to a player (console).
`nakama_ban_account`	write	Ban a player account by user ID (console).
`nakama_unban_account`	write	Remove a ban from a player account (console).

Reliability features

Auto-pagination — nakama_execute_action, nakama_console_list_accounts, and nakama_console_list_storage accept auto_paginate: true (+ optional max_pages, default 5) to follow cursor/next_cursor and merge pages, adding __pages_fetched / __more_available to the result.
Secret redaction — error output is scrubbed of the configured server key / console password, JWTs, and Basic/Bearer header values before it reaches the model.
Healthcheck — nakama_healthcheck probes both surfaces (and verifies admin login); use it first when calls fail.

Typical flow: ask nakama_search_actions for what you want → take the action_id → call nakama_execute_action. The promoted tools are shortcuts for frequent reads.

Related MCP server: Claude-LMStudio Bridge

Install & build

npm install
npm run build

Configuration

All configuration is via environment variables. Defaults match a stock local Nakama dev setup.

Variable	Default	Notes
`NAKAMA_HOST`	`127.0.0.1`	Host for both APIs.
`NAKAMA_PORT`	`7350`	Client API port.
`NAKAMA_CONSOLE_PORT`	`7351`	Console API port.
`NAKAMA_USE_SSL`	`false`	Use `https` instead of `http`.
`NAKAMA_SERVER_KEY`	`defaultkey`	Server key for client authenticate endpoints.
`NAKAMA_CONSOLE_USERNAME`	`admin`	Console admin user.
`NAKAMA_CONSOLE_PASSWORD`	`password`	Console admin password.
`NAKAMA_TIMEOUT_MS`	`15000`	Per-request timeout.

See .env.example. These are secrets — prefer your MCP host's env config over committing them.

Add to an MCP host

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "nakama": {
      "command": "node",
      "args": ["/absolute/path/to/nakama-mcp/dist/index.js"],
      "env": {
        "NAKAMA_HOST": "127.0.0.1",
        "NAKAMA_SERVER_KEY": "defaultkey",
        "NAKAMA_CONSOLE_USERNAME": "admin",
        "NAKAMA_CONSOLE_PASSWORD": "password"
      }
    }
  }
}

Claude Code

claude mcp add nakama -- node /absolute/path/to/nakama-mcp/dist/index.js

Cursor / Windsurf (`~/.cursor/mcp.json` or `~/.codeium/windsurf/mcp_config.json`)

Both read the same mcpServers shape as Claude Desktop:

{
  "mcpServers": {
    "nakama": {
      "command": "node",
      "args": ["/absolute/path/to/nakama-mcp/dist/index.js"],
      "env": { "NAKAMA_SERVER_KEY": "defaultkey", "NAKAMA_CONSOLE_PASSWORD": "password" }
    }
  }
}

VS Code (`.vscode/mcp.json`)

VS Code nests servers under a top-level servers key:

{
  "servers": {
    "nakama": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nakama-mcp/dist/index.js"],
      "env": { "NAKAMA_SERVER_KEY": "defaultkey", "NAKAMA_CONSOLE_PASSWORD": "password" }
    }
  }
}

Any MCP-capable host works — point it at node /absolute/path/to/nakama-mcp/dist/index.js over stdio (env vars default to a stock local Nakama), or at the Remote HTTP transport below.

Remote HTTP transport

By default the server speaks stdio. Set MCP_TRANSPORT=http to run it as a network-reachable streamable-HTTP server that multiple MCP clients can share. It still targets the single Nakama configured by your NAKAMA_* vars; each connected MCP client gets its own isolated player session, and the console admin login is shared.

Variable	Default	Notes
`MCP_TRANSPORT`	`stdio`	Set to `http` to enable the HTTP server.
`MCP_HTTP_HOST`	`127.0.0.1`	Bind address. Loopback by default.
`MCP_HTTP_PORT`	`3000`	Listen port.
`MCP_HTTP_PATH`	`/mcp`	MCP endpoint path.
`MCP_AUTH_TOKEN`	(unset)	Static bearer token required in `Authorization: Bearer …`.
`MCP_SESSION_TTL_MS`	`1800000`	Idle session timeout (30 min).

MCP_TRANSPORT=http MCP_AUTH_TOKEN=s3cret npm start
# nakama-mcp ready -> http://127.0.0.1:3000/mcp (transport=http, auth=on)
curl -s http://127.0.0.1:3000/healthz   # -> {"ok":true}

Security: if you bind a non-loopback address (e.g. MCP_HTTP_HOST=0.0.0.0) the server refuses to start unless MCP_AUTH_TOKEN is set, so Nakama admin is never accidentally exposed. The endpoint is plain HTTP — terminate TLS at a reverse proxy for public hosting. GET /healthz is unauthenticated for load balancers; all /mcp traffic requires the token.

How auth works

Console API: the server auto-logs-in with NAKAMA_CONSOLE_USERNAME / NAKAMA_CONSOLE_PASSWORD on first use, caches the JWT, and refreshes when it expires. You don't call a login tool.
Client API: authenticate endpoints use HTTP Basic with NAKAMA_SERVER_KEY. Every other client endpoint needs a player session — call nakama_authenticate first; the session token is held in memory for the rest of the connection.
RPCs: nakama_call_rpc JSON-encodes the payload as Nakama's REST gateway expects. Pass http_key to call an RPC without a player session.

Usage examples (what to ask Claude)

"Search Nakama for how to ban an account, then ban user <uuid>."
"List the 10 most recent players whose username contains test."
"Show me server status and current latency."
"Authenticate as device demo-1, then write a storage object in collection saves."
"Call the healthcheck RPC."

Troubleshooting

When in doubt, ask Claude to run nakama_healthcheck first — it probes both API surfaces and verifies admin login, and pinpoints which side is failing.

Symptom	Likely cause & fix
`Failed to reach Nakama at http://127.0.0.1:7350`	Nakama isn't running or host/port/SSL are wrong. Start it (`docker compose up -d --wait`) and check `NAKAMA_HOST` / `NAKAMA_PORT` / `NAKAMA_USE_SSL`.
`No player session yet … call nakama_authenticate first`	A client (`:7350`) endpoint was used without a session. Run `nakama_authenticate` (device/custom/email) before other player calls.
`Console login did not return a token`	Wrong admin creds. Check `NAKAMA_CONSOLE_USERNAME` / `NAKAMA_CONSOLE_PASSWORD` (defaults `admin` / `password`).
Client authenticate returns HTTP 401	Wrong `NAKAMA_SERVER_KEY` (default `defaultkey`).
`Unknown action_id '…'`	Use `nakama_search_actions` to find the exact id; the error also suggests close matches.
HTTP mode: every `/mcp` request returns `401`	Missing/incorrect `Authorization: Bearer <MCP_AUTH_TOKEN>` header.
HTTP mode: server won't start, "Refusing to bind …"	You bound a non-loopback host without `MCP_AUTH_TOKEN`. Set a token, or bind `127.0.0.1`.
Tools don't appear in your MCP host	Point the host at the absolute path to `dist/index.js`, run `npm run build` first, and restart the host (configs are read at startup).

The server logs to stderr only (stdout is the protocol stream). In Claude Desktop, check the MCP logs; for the integration test set VERBOSE=1.

Testing against a real Nakama

A docker-compose.yml (Nakama 3.37.0 + CockroachDB) and a live integration test are included.

docker compose up -d          # start Nakama + DB (wait until healthy)
npm run build
npm run test:integration      # drives the MCP server over stdio against the live server
npm run test:http-integration # same, but over the streamable-HTTP transport (SDK client)
docker compose down -v        # stop and wipe

The stdio test exercises the full path end to end: tools/list, console auto-login + status, list accounts, player device authentication, GetAccount, and a storage write/read round-trip. The HTTP test drives the same live backend over the streamable-HTTP transport and also verifies the per-session player-session isolation that only the HTTP transport provides (each MCP session gets its own NakamaClient / player session). Both print a PASS/FAIL summary and exit non-zero on any failure, so they are CI-friendly. Set VERBOSE=1 to see server logs. They honor the same NAKAMA_* env vars as the server (defaults already match the bundled compose).

Continuous integration

.github/workflows/ci.yml runs on every push and PR:

smoke — npm ci → build → resolve + redact + smoke + http + http-reaper + version (unit + stdio/HTTP protocol surface; no Nakama). Fast.
integration — boots Nakama + CockroachDB with docker compose up --wait, then runs npm run test:integration, dumps server logs on failure, and tears down.

Run the same checks locally:

npm test                   # full fast suite, no server needed
npm run test:integration   # needs `docker compose up -d` (stdio)
npm run test:http-integration  # needs `docker compose up -d` (HTTP transport)

Regenerating the API catalog

The bundled data/catalog.json is generated from Nakama's upstream OpenAPI (Swagger 2.0) specs. regen-catalog also resolves request-body $refs into inline field schemas, so nakama_search_actions shows Claude the exact fields (name, type, required, description — including nested objects) each POST/PUT body expects.

Run it on your machine (needs network) to refresh and fully enrich the catalog:

npm run regen-catalog            # uses master
npm run regen-catalog -- v3.37.0 # a specific git ref/tag

The resolver is covered by a unit test (npm run test:resolve).

Install as a desktop extension (MCPB)

For zero-prerequisite installs (no Node, no npm, no build), package the server as an MCPB bundle and install the single file.

npm run mcpb        # builds mcpb-build/ and packs dist-mcpb/nakama-mcp.mcpb

npm run mcpb runs two steps you can also run separately:

npm run mcpb:build — type-checks, bundles the server with esbuild into mcpb-build/server/index.mjs, and stages manifest.json, data/catalog.json, and package.json (the server reads its version from it).
npm run mcpb:pack — packs mcpb-build/ into dist-mcpb/nakama-mcp.mcpb (validates the manifest). A plain cd mcpb-build && zip -r ../dist-mcpb/nakama-mcp.mcpb . also works.

Then drag dist-mcpb/nakama-mcp.mcpb onto Claude Desktop to install. The installer prompts for the connection settings declared in manifest.json (host, ports, HTTPS, server key, console username/password); the server key and console password are stored in the OS keychain.

MCPB is the right choice when Nakama runs on the user's own machine/localhost. If you target a shared or cloud Nakama, a remote HTTP server is the better distribution path (see below).

Distribution / upgrade path

Stdio (the default) is the fastest shape to prototype and run against your own Nakama. Two paths cover wider distribution:

MCPB bundle — package the server with its Node runtime so it installs without prerequisites (best when it still needs to reach a Nakama the user runs locally).
Remote streamable-HTTP — already built in (MCP_TRANSPORT=http); host it once behind a URL (best if it targets a shared/cloud Nakama). Add OAuth in front if you need more than the static bearer token.

The tool layer and Nakama client are transport-agnostic — both transports build the same server via buildMcpServer() in src/server.ts.

Security & disclaimer

This server gives an AI model real, write-capable access to your Nakama instance. nakama_execute_action can call any operation in the catalog, and the console (:7351) tools act with admin authority — they can write/delete storage, send notifications, and ban or unban accounts. Treat it accordingly:

Point it at a dev/staging Nakama, not production, until you trust the workflow. Operations are real and some are irreversible.
Keep credentials in your MCP host's env/secret store, not in committed files. The server key and console password are secrets; error output is scrubbed of them (plus JWTs and Basic/Bearer headers) before it reaches the model, but don't paste them into prompts.
Remote HTTP: always set MCP_AUTH_TOKEN, and don't expose the endpoint without TLS in front. A non-loopback bind without a token is refused by design.
No telemetry. The server makes network calls only to the Nakama you configure — nothing is sent to any third party.

This is an independent, community integration — not an official Heroic Labs product. Use at your own risk; see SECURITY.md to report a vulnerability privately.

Contributing & security

Contributions welcome — see CONTRIBUTING.md for dev setup and the two-tier test workflow.
Changes are tracked in CHANGELOG.md.
Found a security issue? Please report it privately — see SECURITY.md. Don't open a public issue.

License

Apache-2.0 — see LICENSE. Nakama is a trademark of Heroic Labs; this is an independent integration.

Available Tools

14 tools

nakama_authenticateAuthenticate a player (client API)A

Establish a player session for the client API (:7350). Required before calling other client/player endpoints. Supports device, custom, or email auth. The session token is held in memory for subsequent calls.

ParametersJSON Schema

Name	Required	Description
`method`	Yes	Authentication method.
`id`	No	Device or custom ID (for method device/custom).
`email`	No	Email (for method email).
`password`	No	Password (for method email).
`username`	No	Optional username to set when creating the account.
`create`	No	Create the account if it does not exist (default true on Nakama).

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and openWorldHint=true. The description adds the key behavioral detail that 'the session token is held in memory for subsequent calls.' No contradictions. It could mention account creation side effect, but that's covered by schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loading the purpose and prerequisite. Every sentence contributes value without redundancy. Extremely efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, the description covers the core workflow but omits return value details and error conditions. It adequately explains the prerequisite and token handling, but more context on expected outputs would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are well-documented. The description only summarizes 'Supports device, custom, or email auth' and mentions token behavior, adding no additional meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Establish a player session for the client API (:7350)', which is a specific verb+resource combination. The tool's purpose is clearly differentiated from sibling tools that handle admin actions (ban, get, etc.) or other operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Required before calling other client/player endpoints', providing clear when-to-use guidance. It mentions supported auth methods but does not give exclusions or alternatives. Siblings don't overlap, so ambiguity is low.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_ban_accountBan a player account (console)B

Destructive

Ban a player account by user ID via the console API.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Player user ID to ban.

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint: true, so the description adds little beyond stating the action. It does not explain the behavioral impact (e.g., immediate block on login, data retention, reversibility). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no unnecessary words. It is front-loaded with the core action. However, it could be slightly more structured (e.g., including a note on side effects or success response).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no output schema, the description is incomplete. It does not mention return values, error conditions, or what the agent should expect after invocation. The agent lacks critical context for safe use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single parameter 'id' with a clear description. The tool description does not add any extra semantics beyond what the schema provides. With 100% schema coverage, baseline score 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Ban'), the resource ('player account'), and the method ('by user ID via the console API'). It distinguishes itself from sibling tools like nakama_unban_account by the specificity of 'ban' and 'console API'. The title reinforces this.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to ban a player account, but it lacks explicit guidance on when to use this tool versus alternatives like nakama_unban_account (or other console tools). No prerequisites or conditions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_call_rpcCall a Nakama server RPCA

Invoke a registered runtime RPC function by id over the client API. Pass payload as a JSON object or string; it is encoded as the gateway expects. Provide http_key to call an RPC without a player session; otherwise authenticate first with nakama_authenticate.

ParametersJSON Schema

Name	Required	Description
`id`	Yes	Registered RPC function id.
`payload`	No	RPC payload (object or string).
`http_key`	No	Server HTTP key for unauthenticated RPC calls.

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions encoding behavior but does not disclose potential side effects, error states, or the nature of mutations. Annotations indicate a non-read-only operation, but the description adds little behavioral context beyond the invocation mechanism.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with front-loaded purpose and efficient usage conditions. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a general RPC invocation tool, but lacks details on return values, error handling, or prerequisites beyond authentication. The absence of an output schema increases the need for completeness, which is partially met.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While schema coverage is 100%, the description adds value by explaining that the payload is encoded as the gateway expects and clarifies the role of http_key for unauthenticated calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool invokes a registered runtime RPC function by id. It distinguishes itself from authentication and other tools implicitly, but does not explicitly differentiate from sibling 'nakama_execute_action'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use http_key (for unauthenticated calls) and to authenticate first with nakama_authenticate otherwise. However, it does not discuss when to avoid this tool in favor of alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_console_get_accountGet a player account (console)A

Read-only

Fetch a single player account (profile, wallet, devices, linked logins) by user ID via the console API.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Player user ID (UUID).

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds value by specifying exactly what data is returned (profile, wallet, devices, linked logins), which helps the agent understand the output without an explicit output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and resource. Every word adds value, and there is no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter, no output schema, and annotations covering safety, the description is sufficiently complete. It enumerates the main components of the response (profile, wallet, etc.) and relates to sibling tools (e.g., console_list_accounts). Slight deduction for not mentioning pagination or limitations, but acceptable for a simple fetch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the parameter 'id' as 'Player user ID (UUID)' with 100% coverage. The description mentions 'by user ID' but does not add additional meaning beyond the schema. Baseline of 3 is appropriate when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch') and the resource ('a single player account'), and specifies the return data (profile, wallet, devices, linked logins). It distinguishes itself from sibling tools like nakama_console_list_accounts (which lists accounts) and others through the 'single account' scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching a single account by user ID via the console API, but it does not explicitly state when to use this tool versus alternatives (e.g., when to use list_accounts instead). No guidance on when not to use this tool is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_console_get_statusGet server status (console)A

Read-only

Return Nakama node status and lightweight service metrics (CPU, memory, latency, presences) via the console API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint. Description adds context by listing the specific metrics returned, and mentions 'via the console API', implying authentication context not covered by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 18 words, front-loaded with action and resource, no redundant words. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description explains what the tool returns and mentions the API context. For a parameterless status tool with no output schema, it covers the essential aspects, though it omits output format and error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema coverage, description adds meaning beyond schema by detailing the return value contents (CPU, memory, etc.), which helps the agent understand what data it will receive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Return' and resource 'Nakama node status and lightweight service metrics', listing concrete metrics (CPU, memory, latency, presences). It distinguishes itself from siblings like 'nakama_healthcheck' by specifying a more detailed status via the console API.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., nakama_healthcheck). No mentions of prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_console_list_accountsList player accounts (console)A

Read-only

List/search player accounts via the console API. Optional filter by user ID or username.

ParametersJSON Schema

Name	Required	Description
`filter`	No	User ID or username filter.
`tombstones`	No	Search only recorded deletes.
`cursor`	No	Pagination cursor.
`auto_paginate`	No	Follow cursors and merge all pages.
`max_pages`	No	Max pages when auto_paginate (default 5).

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint and openWorldHint. Description adds 'via the console API' but no additional behavioral context beyond schema. Does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, clear and front-loaded. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should explain return values. It does not. Parameter count is 5 but all optional; adequate for a listing tool but incomplete on response format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline 3. Description only repeats filter parameter; no extra semantics for cursor, auto_paginate, etc.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'list/search' targeting 'player accounts' via console API. Distinguishes from siblings focused on authentication, banning, storage, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mentions optional filter but does not differentiate from sibling 'nakama_console_get_account' for single account retrieval. No guidance on when to use list vs get or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_console_list_storageList storage objects (console)A

Read-only

List storage objects via the console API, optionally filtered by collection, key, and/or owner user ID.

ParametersJSON Schema

Name	Required	Description
`collection`	No	Storage collection name.
`key`	No	Storage key.
`user_id`	No	Owner user ID.
`cursor`	No	Pagination cursor.
`auto_paginate`	No	Follow cursors and merge all pages.
`max_pages`	No	Max pages when auto_paginate (default 5).

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and openWorldHint, so the description adds little behavioral context. It mentions the console API and filtering but does not elaborate on pagination behavior or response format, which are beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, efficient and front-loaded. Every word contributes to the purpose, with no extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and 6 parameters, the description lacks details about pagination behavior and return format. It covers the basic filtering but misses important operational context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description only reiterates three filter parameters without adding new semantics beyond the schema descriptions. It omits mention of cursor, auto_paginate, and max_pages.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists storage objects via the console API, with optional filters. It distinguishes from siblings like nakama_write_storage_object by specifying the read operation and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as other console list tools or search tools. No when-not-to-use or context is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_execute_actionExecute a Nakama API actionA

Destructive

Execute any Nakama operation by its action_id (from nakama_search_actions). Provide path_params, query_params, and/or body as needed. Auth is handled automatically: console actions auto-login with configured admin credentials; client actions use the player session from nakama_authenticate; authenticate endpoints use the server key. For calling server RPCs prefer nakama_call_rpc (it encodes the payload correctly).

ParametersJSON Schema

Name	Required	Description
`action_id`	Yes	Action ID returned by nakama_search_actions, e.g. 'ListAccounts' or 'Nakama_WriteStorageObjects'.
`path_params`	No	Values for {placeholders} in the path, e.g. { id: '<uuid>' }.
`query_params`	No	Query-string parameters.
`body`	No	JSON request body (for POST/PUT/DELETE actions that take one).
`auto_paginate`	No	For GET list endpoints: follow `cursor`/`next_cursor` and merge pages.
`max_pages`	No	Max pages to fetch when auto_paginate is set (default 5).

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes automatic auth handling, noting different credential sources for console vs. client vs. authenticate endpoints. Mentions pagination behavior via auto_paginate and max_pages. No contradiction with annotations (destructiveHint=true, readOnlyHint=false).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: purpose, auth handling, and sibling distinction. No filler, but might benefit from bullet points for clarity. Still, efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, auth, pagination, and alternative tools. Lacks explanation of return values or error handling, but output schema is absent and the tool is well-described for its intended use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides 100% coverage with descriptions. The description repeats 'Provide path_params, query_params, and/or body as needed' but adds little beyond schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Execute any Nakama operation by its action_id' with specific verb and resource. References nakama_search_actions as the source of action_id. Distinguishes from sibling tool nakama_call_rpc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises when to use this tool vs. alternatives: 'For calling server RPCs prefer nakama_call_rpc (it encodes the payload correctly).' Also explains auth context for different action types (console, client, authenticate).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_healthcheckCheck Nakama connectivityA

Read-only

Probe both APIs: the client /healthcheck endpoint and a console status call (which also verifies admin login). Returns a per-surface reachability report. Use this first when calls are failing.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and openWorldHint=true. The description adds that the tool performs two distinct probes and verifies admin login, which is useful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action, and no wasted words. Each sentence adds value: what it does, how it works, and when to use it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple healthcheck tool with no parameters and read-only annotations, the description fully covers what the agent needs: purpose, behavioral details, and usage context. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so schema coverage is 100%. The description correctly does not add parameter info, as none is needed. Baseline score for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool probes two specific endpoints (client /healthcheck and console status) and returns a reachability report. It is specific and distinct from sibling tools like nakama_console_get_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to 'Use this first when calls are failing,' providing clear context for troubleshooting. Does not discuss when not to use or alternatives, but the guidance is straightforward.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_search_actionsSearch Nakama API actionsA

Read-only

Search the Nakama API catalog (179 operations: 87 client, 92 console) by natural-language intent and get matching action IDs, HTTP method/path, summaries, and parameter schemas. Use this to discover the action_id you then pass to nakama_execute_action. Results include resolved request-body field schemas when available. Examples: 'list players', 'write storage object', 'leaderboard records', 'ban account', 'active matches'.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Natural-language description of what you want to do.
`surface`	No	Limit to 'client' (player-facing :7350) or 'console' (admin :7351) API.
`limit`	No	Max results (default 20).

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and description adds that results include resolved request-body field schemas when available, plus the catalog size (179 operations). No destructive behavior, so description adds useful context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines purpose and output, second provides usage guidance and examples. No wasted words, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search-only read tool with no output schema, the description explains exactly what results contain (action IDs, method/path, summaries, param schemas) and the context that it serves as a discovery step before execution. Complete and sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description adds example queries but does not provide additional meaning beyond what the input schema already documents for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool searches a catalog by natural-language intent and returns matching actions with IDs, HTTP method/path, summaries, and parameter schemas. Distinct from siblings like nakama_execute_action which uses the discovered action_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use this to discover the action_id you then pass to nakama_execute_action', providing clear when-to-use guidance. Includes example queries. Lacks explicit when-not-to-use, but context implies not for direct execution.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_send_notificationSend a notification (console)B

Send an in-app notification to a player via the console API. Use a positive app-defined code (<=0 is reserved).

ParametersJSON Schema

Name	Required	Description
`user_id`	Yes	Recipient player user ID.
`subject`	Yes	Notification subject/title.
`content`	No	Content (object or JSON string).
`code`	No	App-defined notification code (default 0).
`persistent`	No	Persist for offline delivery (default true).

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and openWorldHint=true, but the description does not disclose additional behavioral traits such as side effects, authentication requirements, rate limits, or what happens on successful send. The description adds no behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 5 parameters and no output schema, the description does not explain return values, error states, or behavior of the 'persistent' parameter. Missing context for what happens after sending.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. The description adds meaningful constraint for the 'code' parameter ('Use a positive app-defined code (<=0 is reserved)'), which clarifies a nuance not in the schema. Other parameters are not elaborated but schema descriptions are sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Send an in-app notification to a player via the console API.' It uses a specific verb and resource, and distinguishes from sibling tools which cover authentication, bans, RPC, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. The only usage advice is about the 'code' parameter (positive values). No context for exclusion or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_unban_accountUnban a player account (console)A

Remove a ban from a player account by user ID via the console API.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Player user ID to unban.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate mutation (readOnlyHint=false). Description adds no extra side effects, permissions, or constraints beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One highly efficient sentence with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with one parameter; description is sufficient. Could mention admin context but not strictly necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameter meaning. Description adds no additional context beyond what schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the action: 'Remove a ban from a player account by user ID via the console API.' Differentiates from sibling 'nakama_ban_account'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when/when-not guidance, but implies use as opposite of ban. Lacks prerequisites or context for using this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_write_leaderboard_recordWrite a leaderboard record (client)A

Submit a score to a leaderboard as the authenticated player (call nakama_authenticate first).

ParametersJSON Schema

Name	Required	Description
`leaderboard_id`	Yes	Leaderboard ID.
`score`	Yes	Score (int64).
`subscore`	No	Optional tie-breaker subscore (int64).
`metadata`	No	Optional metadata (object or JSON string).

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=false and openWorldHint=true. The description adds the authentication requirement but does not disclose other behavioral traits such as overwrite behavior or error handling. For a write operation, additional clarity would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose and prerequisite, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and full schema coverage, the description provides adequate context for a write operation. It could mention the requirement that the leaderboard ID must exist, but this is not critical for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema for parameters like subscore or metadata.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Submit' and the resource 'leaderboard', and specifies the context 'as the authenticated player'. This distinguishes it from sibling tools like nakama_write_storage_object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions the prerequisite of calling nakama_authenticate first, guiding the agent on when to use this tool. It does not mention alternatives, but the name and context are sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nakama_write_storage_objectWrite a storage object (client)A

Write or update a single storage object as the authenticated player (call nakama_authenticate first). Pass value as an object or JSON string. Use version '*' to require the object not already exist.

ParametersJSON Schema

Name	Required	Description
`collection`	Yes	Collection name.
`key`	Yes	Object key.
`value`	Yes	Object value (object or JSON string).
`version`	No	Optimistic-concurrency version; '*' means must-not-exist.
`permission_read`	No	0=none, 1=owner (default), 2=public.
`permission_write`	No	0=none, 1=owner (default).

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a write operation (readOnlyHint=false) and safety in open world (openWorldHint=true). The description adds authentication prerequisite and version semantics, but does not disclose rate limits, destruction, or response behavior. Functional but not additive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence states purpose and prerequisite, the second covers key parameter usage. Perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description covers the main use case and version parameter. Missing return value info, but otherwise adequate given complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to pass value (object or JSON string) and the meaning of version '*', which goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (write/update) and resource (storage object), and specifies the context (authenticated player) with a prerequisite note. It distinguishes from sibling tools like nakama_write_leaderboard_record by focusing on storage objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly requires calling nakama_authenticate first, and explains the version '*' usage. However, it does not exclude alternatives or mention when not to use this tool, which would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

14 tool updatesv0.1.0Jun 19, 2026
- First observednakama_authenticate
- First observednakama_ban_account
- First observednakama_call_rpc
- First observednakama_console_get_account
- First observednakama_console_get_status
- First observednakama_console_list_accounts
- First observednakama_console_list_storage
- First observednakama_execute_action
- First observednakama_healthcheck
- First observednakama_search_actions
- First observednakama_send_notification
- First observednakama_unban_account
- First observednakama_write_leaderboard_record
- First observednakama_write_storage_object

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-06-19 22:05 across 14 tools

Disambiguation4/5

Most tools have clear purposes, with console and client operations separated by naming. However, nakama_call_rpc and nakama_execute_action overlap in functionality, potentially causing confusion about which to use for RPC calls.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case, with console operations consistently prefixed by 'console_' and client operations by no prefix. This makes the set predictable and easy to navigate.

Tool Count5/5

With 14 tools, the count is well-scoped for a game backend server covering authentication, account management, storage, leaderboards, notifications, RPCs, and healthcheck. This is within the ideal 3–15 range.

Completeness5/5

The tool set covers common tasks directly and provides a generic search-execute mechanism that can invoke all 179 Nakama API operations, ensuring no dead ends. Minor omissions like storage delete are handled via execute_action.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Remote Desktop CommanderOAuth
app.desktopcommander
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Shell Access OS Automation
237
Motecloud MemoryOAuth
io.github.motecloud
Cloud-hosted MCP server for durable AI memory
Knowledge & Memory Cloud Platforms
2
server B
io.cycloid.mcp
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Developer Tools CI/CD & DevOps Cloud Platforms
2
SupabaseOAuth
com.supabase
MCP server for interacting with the Supabase platform
Cloud Platforms Databases Developer Tools
32,908

Related MCP Servers

Notion MCP Server
Note Taking Content Management Systems App Automation
suekou
A
license
A
quality
A
maintenance
MCP Server for the Notion API, enabling Claude to interact with Notion workspaces.
Updated 2 months ago (2026-07-31 07:14 UTC)
31
801 npm
920
MIT
Claude-LMStudio Bridge
Autonomous Agents Code Execution
infinitimeless
F
license
Not graded
quality
F
maintenance
An MCP server that allows Claude to interact with local LLMs running in LM Studio, providing access to list models, generate text, and use chat completions through local models.
Updated a year ago (2025-03-21 13:27 UTC)
13
-
Discord MCP Server
Communication Developer Tools
RossH121
A
license
A
quality
D
maintenance
An MCP server that allows Claude to interact with Discord by providing tools for sending/reading messages and managing server resources through Discord's API.
Updated 2 years ago (2025-03-07 03:43 UTC)
19
88 npm
MIT
haksnbot-tools
Games & Gamification Autonomous Agents
haksndot
A
license
Not graded
quality
D
maintenance
An MCP server that lets Claude control a Minecraft bot with 40+ actions including movement, combat, crafting, and inventory management. Built on Mineflayer, it supports Microsoft authentication, pathfinding, and auto-reconnect.
Updated 6 months ago (2026-03-10 13:39 UTC)
3
MIT

nakama-mcp

Tools

Reliability features

Install & build

Configuration

Add to an MCP host

Claude Desktop (claude_desktop_config.json)

Claude Code

Cursor / Windsurf (~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json)

VS Code (.vscode/mcp.json)

Remote HTTP transport

How auth works

Usage examples (what to ask Claude)

Troubleshooting

Testing against a real Nakama

Continuous integration

Regenerating the API catalog

Install as a desktop extension (MCPB)

Distribution / upgrade path

Security & disclaimer

Contributing & security

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Claude Desktop (`claude_desktop_config.json`)

Cursor / Windsurf (`~/.cursor/mcp.json` or `~/.codeium/windsurf/mcp_config.json`)

VS Code (`.vscode/mcp.json`)