Skip to main content

Best practices

Follow these practices to get accurate results and stay in control when you use the Nium MCP Server.

Protect your API key​

  • Store your API key in an environment variable, such as NIUM_API_KEY, and reference it in your client config. Avoid pasting the key directly into config files where your client supports environment variables.
  • Add any project-level config file that contains your key, such as .cursor/mcp.json, .mcp.json, or .codex/config.toml, to .gitignore.
  • Never paste your API key into a prompt or share it in a chat.
  • Rotate your key in Nium Portal if you suspect it is exposed.
tip

Keys are environment-specific. The Nium MCP Server currently runs against Sandbox only, so use a Sandbox key.

Guard against prompt injection​

You're responsible for guarding against prompt injection when you use MCP tools. Content returned by a tool, such as a beneficiary name or a transaction reference, can contain instructions that your agent might follow.

  • Use the MCP Server only with Nium objects you trust.
  • Treat text returned from Sandbox data as data, not as instructions.
  • Stop the session if your agent starts an action you didn't ask for.

Treat the API spec as the source of truth​

  • Use nium_api_details for the API contract. Guides from nium_docs_read provide flow and context only.
  • If a guide and the API spec disagree, trust nium_api_details.
  • Don't rely on your agent's memory of Nium APIs. Ask it to look up the operation each time.

Follow Best Practices while Prompting​

  • Mention Nium explicitly in your prompt, for example "Using Nium, ...", so your agent picks the Nium tools instead of answering from general knowledge.
  • Name the specific outcome you want, such as "create a corporate customer", not "set up an account".
  • Provide the values your agent can't guess, such as country, currency, amount, and beneficiary details.
  • Break long workflows into steps. Confirm each step succeeded before you move to the next one.
  • Ask your agent to show the request it plans to send before it runs a write action.

Less effective

"Set up a customer and pay someone."

More effective

"Using Nium, create a corporate customer called Meridian Logistics in Sandbox. Show me the request before you send it."

Control Sandbox actions​

nium_api_write executes real Sandbox operations, such as creating customers, adding beneficiaries, funding wallets, and initiating payouts.

  • Review each write action before you confirm it.
  • Don't enable auto-approval for tool calls in your client. Approve each write call manually.
  • Use nium_api_read to verify the result of a write action before you continue.
  • Choose between defaults and custom values deliberately when your agent creates a customer or beneficiary. Use defaults for quick tests. Specify the type and region yourself when your test depends on them.

Generate integration code safely​

  • Tell your agent you're building an integration, not running a workflow. This returns the integration playbook instead of Sandbox actions.
  • Specify your language, framework and Tech Stack in the prompt. Node.js, TypeScript, Python, Go, and curl produce the most reliable output.
  • Ask for error handling for the most common failure states.
  • Read and test generated code in Sandbox before you use it anywhere else.
  • Keep API keys out of generated code. Load them from environment variables or a secrets manager.

Keep context focused​

  • Start a new chat for each distinct task. Long sessions can cause your agent to lose earlier details.
  • Restate key identifiers, such as customer hashes and wallet IDs, when you continue a workflow in a new chat.
  • Enable only the MCP servers you need for the task.

Verify before you go live​

  • Treat results from the MCP Server as a starting point. Review them against the Nium API documentation before you rely on them.
  • Test your integration end to end in Sandbox.
  • Remember that the MCP Server can't access Production yet. When you move to Production, you use a different API key and server URL.

Next steps​

LLM-ready documentation:: llms.txt and llms-full.txt
Was this page helpful?