Agent guide: gala-mcp-server

This page is for an AI agent that drives @gala-chain/gala-mcp-server, or that helps a person set it up. The server exposes the Gala SDKs as MCP tools and prompts; the tool calls below are shown as mcp blocks, and a test holds every call to a real tool with parameters its schema declares.

Which package for which job

Job	Package
Drive wallets, GALA transfers, bridging, Launchpad trading and GSwap swaps from an MCP client	@gala-chain/gala-mcp-server (this package): npm install -g @gala-chain/gala-mcp-server@next
Write application code against GalaChain	@gala-chain/gala-core-sdk and the product SDKs below; read their agent guides
Launchpad pools, buys, sells, token creation in code	@gala-chain/launchpad-sdk
GSwap quotes, swaps, liquidity in code	@gala-chain/gswap-sdk

Each package publishes an agent guide at /<package>/agents.md on the docs site (listed in /llms.txt), and gala_launchpad_search_gala_docs searches them all.

Find the right tool

Tools are grouped in toolsets (core, launchpad, gswap; composite is enabled when both launchpad and gswap are). GALA_TOOLSETS or --toolsets selects them, so a call to a tool of a toolset that is not selected does not exist. The per-toolset reference pages list every tool with its parameters, and the same data is machine-readable at /mcp/tools.json (index) and /mcp/<toolset>/tools.json.

// Which docs answer a question, offline too (a bundled index backs the site's):
gala_launchpad_search_gala_docs({
  query: 'transfer GALA to an eth address',
  package: 'gala-core-sdk'
})

// A code example and the packages it uses, with the docs version next to the SDK version this server runs:
gala_launchpad_explain_sdk_usage({
  topic: 'buy-tokens'
})

// Describe an HTTP endpoint by operation id, exact path + method, or a short query:
gala_launchpad_describe_endpoint({
  service: 'dex-backend',
  operationId: 'getPools'
})

Recipes

Check the session before writing

// Is a wallet configured, and which environment is the session on?
gala_launchpad_get_wallet({})
gala_launchpad_get_environment({})

A server started without PRIVATE_KEY is read-only: the read tools work and a write tool answers an error. Never put a private key in a tool argument when the server already has one configured.

Transfer GALA

gala_launchpad_transfer_gala({
  recipientAddress: 'eth|1234567890123456789012345678901234567890',
  amount: '1.5'
})

amount is whole GALA as a decimal string. recipientAddress is eth|<40 hex digits> or a bare 0x<40 hex> (converted); eth|0x<hex> is refused.

Buy a Launchpad token

Quote first, then buy with the quote's amount and the slippage bound.

gala_launchpad_calculate_buy_amount({
  tokenName: 'anime',
  amount: '100',
  type: 'native'
})

gala_launchpad_buy({
  tokenName: 'anime',
  amount: '100',
  type: 'native',
  expectedAmount: '1000',
  slippageToleranceFactor: 0.01
})

expectedAmount is the amount the quote answered, not a number to invent.

Quote and swap on the DEX

gala_launchpad_get_swap_quote_exact_input({
  fromToken: 'GALA|Unit|none|none',
  toToken: 'GUSDC|Unit|none|none',
  amount: '100'
})

Create a Launchpad token

gala_launchpad_check_token_name({
  tokenName: 'anime'
})

gala_launchpad_launch_token({
  tokenName: 'anime',
  tokenSymbol: 'ANIME',
  tokenDescription: 'Example token',
  tokenImage: 'https://example.test/anime.png'
})

Invariants

• Every mcp tool call shown on this package's docs pages names a tool of the manifest, with parameters its schema declares, and the full server registers exactly the manifest's tools and prompts. Enforced by packages/gala-mcp-server/src/__tests__/docs-tool-calls.test.ts ("names only tools of the manifest, with parameters their schema declares") and packages/gala-mcp-server/src/toolsets/__tests__/groups.test.ts ("the full server registers every tool and prompt of the manifests").
• A toolset that is not selected is never loaded, so its SDK is not either, and a selection offers only the prompts and SDK-usage topics whose every tool is registered. Enforced by packages/gala-mcp-server/src/toolsets/__tests__/module-graph.test.ts ("module graph per selection") and packages/gala-mcp-server/src/toolsets/__tests__/groups.test.ts ("loadToolsets, every selection").
• The server's own address checks take exactly the forms launchpad-sdk takes (eth|<EIP-55 digits>, a checksummed 0x<40 hex>, a client| alias), and eth|0x<hex> is REFUSED with core's message naming the correct spelling. Enforced by packages/gala-mcp-server/src/__tests__/address-forms-sync.test.ts ("the server address checks take exactly the forms launchpad-sdk takes").
• The GALA transfer tool accepts the spellings launchpad-sdk takes and hands them to core as written, and refuses eth|0x<hex>. Enforced by packages/gala-mcp-server/src/toolsets/core/gala/__tests__/parity.test.ts ("1.0.0-rc.5/rc.6: the address spellings launchpad-sdk takes are accepted and handed to core as written; eth|0x... is refused").
• A token name is 1 to 25 letters and digits, like the SDK's. Enforced by packages/gala-mcp-server/src/__tests__/common-schemas-sync.test.ts ("TOKEN_NAME_SCHEMA caps a token name at 25 characters, like the SDK (20 before the backend raised it)").
• The environment is prod (the default) or stage; anything else is refused. Enforced by packages/gala-mcp-server/src/session/__tests__/session.test.ts ("ENVIRONMENT is prod (default) or stage; anything else is refused").
• Switching the environment prepares every toolset's client first and commits them all together, so a switch that cannot be built changes nothing and tools never see half of a switch. Enforced by packages/gala-mcp-server/src/session/__tests__/session.test.ts ("one participant that cannot be built refuses the switch: the others are aborted, nothing changes").
• The docs tools are offline-safe: a failing site is remembered rather than asked on every call, the stale cache answers when the site fails, and the bundled index answers when there is no cache. Enforced by packages/gala-mcp-server/src/toolsets/core/tools/docs/__tests__/docs-source.test.ts ("serves the stale cache when the site fails, and remembers the failure so it is not asked on every call") and packages/gala-mcp-server/src/toolsets/core/tools/docs/__tests__/docs-source.test.ts ("falls back to the bundled index with no cache, and throws a clear error when there is none").

Failures

Tool errors answer text beginning Error: with a tip; the SDK's own error code is in the message.

Failure	Meaning	Fix
A tool the client cannot find	The tool's toolset is not selected.	Set GALA_TOOLSETS (or --toolsets) to include it and restart the server.
An error saying a wallet is required, on a write	The session has no wallet (read-only mode).	Configure PRIVATE_KEY, or call gala_launchpad_set_wallet once.
An address refused for eth|0x...	An address was written with a 0x after eth|.	Write eth|<EIP-55 digits> or the bare 0x<hex>.
Data of the wrong network	The session environment is not the one meant (the default is prod).	Check gala_launchpad_get_environment; switch with gala_launchpad_switch_environment.
No docs index available	The docs site is unreachable and this build has no bundled index.	Set GALA_DOCS_BASE_URL to a reachable site, or upgrade the server.