MCP server setup

@gala-chain/gala-mcp-server is a stdio MCP server: the client starts it as a child process and talks to it over stdin and stdout. Every client below needs the same three things: the command that starts it, the environment it runs with, and a restart of the client after a change.

The command

npx -y @gala-chain/gala-mcp-server@next

npx fetches and runs the server, so nothing needs installing. To install it once instead:

npm install -g @gala-chain/gala-mcp-server@next
gala-mcp

The bin is gala-mcp. The server needs Node.js 20 or newer. While the server is a release candidate the tag is required: @next or the exact version, because a range such as ^1.0.0 matches no prerelease.

The only command line flag is --toolsets. The server has no --help, and a flag it does not know is ignored rather than refused, so a mistyped flag silently does nothing: check the startup log instead.

gala-mcp --toolsets core,gswap

Environment

Variable	Meaning	Default
`ENVIRONMENT`	`prod` (the real GalaChain network) or `stage` (the test network). Anything else stops the server at startup.	`prod`
`PRIVATE_KEY`	The signing key. Without it the server is read-only: every read works and a write says it needs a wallet.	unset
`WALLET_ADDRESS`	An optional identity override, passed to the SDK as `galaChainAddress`. It must be the address of `PRIVATE_KEY`, or a `client\|` alias registered for it.	unset
`GALA_TOOLSETS`	Comma list of `core`, `launchpad`, `gswap`. The `--toolsets` flag wins over it.	all
`TIMEOUT`	Request timeout in milliseconds.	`30000`
`DEBUG`	`true` for verbose logs on stderr.	unset
`ETHEREUM_RPC_URL`	Ethereum RPC endpoint for bridge operations.	the SDK's endpoints
`SOLANA_RPC_URL`	Solana RPC endpoint for bridge operations.	public Solana endpoints
`SOLANA_PRIVATE_KEY`	Solana signing key, for bridge operations that need one.	unset
`STREAM_WEBSOCKET_URL`	Custom stream WebSocket endpoint.	the SDK's endpoint
`STREAM_ADMIN_API_KEY`	Stream administration access.	unset
`USER_API_KEY`	User API authentication.	unset
`GALA_DOCS_BASE_URL`	The docs site the documentation tools read.	`https://docs.gala.com`
`GALA_DOCS_CACHE_DIR`	Where the fetched docs index is kept.	the user cache directory
`GALA_DOCS_CACHE_TTL_SECONDS`	How long the cached docs index stays fresh.	`3600`
`GALA_DOCS_OFFLINE`	`1` never asks the docs site; the bundled index answers.	unset

A configuration mistake (a malformed key, an ENVIRONMENT that is not prod or stage, a WALLET_ADDRESS that is not the key's address) is reported by every tool call with what to fix, so the assistant can tell you.

Toolsets

Without a selection the server loads every toolset. Selecting fewer keeps tools you will not use out of the model's context, and a toolset you do not select is never loaded.

Selection	Tools	Prompts
all (default)	324	286
`core`	47	30
`core,launchpad`	289	243
`core,gswap`	79	64

core holds the wallet, the session environment, the GALA balance and transfer, bridging and the documentation tools, so almost every selection should include it. composite is not selectable: it is enabled when launchpad and gswap both are. An unknown name, an empty entry or composite stops the server at startup with a message naming the valid toolsets.

Claude Code

Add the server to the current project, read-only on the test network:

claude mcp add gala -e ENVIRONMENT=stage -- npx -y @gala-chain/gala-mcp-server@next

Only the part after -- is the server's command; -e sets an environment variable of the server. Add -s user to make it available in every project, and -e GALA_TOOLSETS=core,gswap to select toolsets. Do not put a signing key on this command line: it lands in your shell history and in the client's configuration file in clear text.

To share a configuration with a team without sharing a key, commit a project .mcp.json that reads the key from each person's own environment (Claude Code expands ${NAME} in it):

{
  "mcpServers": {
    "gala": {
      "command": "npx",
      "args": ["-y", "@gala-chain/gala-mcp-server@next"],
      "env": {
        "ENVIRONMENT": "stage",
        "GALA_TOOLSETS": "core,gswap",
        "PRIVATE_KEY": "${GALA_STAGE_KEY}"
      }
    }
  }
}

If GALA_STAGE_KEY is not set, Claude Code reports the missing variable instead of starting the server: that is the safe failure. Run /mcp in a session to see whether the server is connected.

Claude Desktop

Edit claude_desktop_config.json (Settings, Developer, Edit Config; on macOS it is under ~/Library/Application Support/Claude/, on Windows under %APPDATA%\Claude\):

{
  "mcpServers": {
    "gala": {
      "command": "npx",
      "args": ["-y", "@gala-chain/gala-mcp-server@next"],
      "env": {
        "ENVIRONMENT": "prod"
      }
    }
  }
}

Restart Claude Desktop. This file does not read your shell environment, so a key you add to its env block sits in that file in clear text: add one only for a wallet you would accept losing, and read security and keys first.

Cursor

Cursor reads the same mcpServers shape from ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "gala": {
      "command": "npx",
      "args": ["-y", "@gala-chain/gala-mcp-server@next"],
      "env": {
        "ENVIRONMENT": "stage",
        "PRIVATE_KEY": "${env:GALA_STAGE_KEY}"
      }
    }
  }
}

Cursor expands ${env:NAME} from the environment it was started in. Restart Cursor, or toggle the server in its MCP settings, after a change.

Any other stdio client

An MCP client that launches stdio servers needs only the command, its arguments and the environment:

{
  "command": "gala-mcp",
  "args": ["--toolsets", "core,launchpad"],
  "env": {
    "ENVIRONMENT": "stage"
  }
}

With the SDK of your own agent, start gala-mcp (or the npx command above) as a child process over stdio and list its tools.

Check that it works

The client's own server list says whether the process started. Then ask the assistant to run these, which read without a key:

gala_launchpad_get_environment({})
gala_launchpad_has_wallet({})
gala_launchpad_search_gala_docs({
  query: 'which toolsets does the server have'
})

The server also logs its enabled toolsets and its tool and prompt counts to stderr at startup; most clients show a server's log in their MCP settings.

The syntax of each client's own configuration file belongs to that client and can change; the server's side (the command, --toolsets and the environment variables above) is checked against the code in CI.

The command​

Environment​

Toolsets​

Claude Code​

Claude Desktop​

Cursor​

Any other stdio client​

Check that it works​