Nium Atlas MCP Server | Connect AI agents to Atlas

01 · Overview

One interface for four Atlas product areas.

The server exposes the repository-backed catalogue used by this Atlas application. It does not run an AI model. Your connected agent decides when to call a tool.

Payouts

01

Countries, currencies, methods, speeds and capabilities

227 entries

Fund & Collect

02

Funding currencies, services, rails and platforms

10 entries

Card Issuing

03

Markets, currencies, market types and schemes

7 entries

FX

04

Currency pairs, settlement behaviour and use cases

10 entries

02 · Connect

Choose how your client connects.

Use local STDIO when the client and Atlas checkout are on the same machine. Use Streamable HTTP only after an Atlas administrator provides an HTTPS endpoint and a scoped token.

Local subprocess

Recommended

STDIO

The MCP client launches Laravel as a local subprocess. No Bearer token is required.

Administrator provisioned

Streamable HTTP

The client connects to the protected Atlas endpoint with an operator-issued Sanctum token.

Before connecting

Prepare the local application.

Use PHP 8.3 or later, install Composer dependencies and complete the normal MySQL setup. Data imports are for authorised maintainers.

Local application setup

composer install
php -d memory_limit=512M artisan migrate
php -d memory_limit=512M artisan atlas:import-payout-methods
php -d memory_limit=512M artisan atlas:import-card-issuance

Option A · Local

Connect with STDIO.

Replace the example path with the absolute path to this checkout. The final argument is the registered server handle and must remain nium-atlas.

Codex CLI

codex mcp add nium-atlas -- \
  php -d memory_limit=512M \
  /absolute/path/to/nium-atlas/artisan \
  mcp:start nium-atlas

Generic MCP client JSON

{
  "mcpServers": {
    "nium-atlas": {
      "command": "php",
      "args": [
        "-d",
        "memory_limit=512M",
        "/absolute/path/to/nium-atlas/artisan",
        "mcp:start",
        "nium-atlas"
      ]
    }
  }
}

Client settings vary. Find the setting for local MCP servers, then enter the same command and arguments shown above.

Verify with Laravel MCP Inspector

php -d memory_limit=512M artisan mcp:inspector nium-atlas

Option B · Remote

Connect over Streamable HTTP.

Ask an Atlas administrator for the deployed HTTPS endpoint and a Sanctum token with the mcp:read ability.

Application endpoint

https://atlas.we-saas.com/mcp/atlas

This is the endpoint for the current application URL. It is not a public deployment guarantee.

Codex CLI with token environment variable

codex mcp add nium-atlas-http \
  --url https://atlas.we-saas.com/mcp/atlas \
  --bearer-token-env-var NIUM_ATLAS_MCP_TOKEN

Keep the token out of shell history, source control, page source and prompts. Populate NIUM_ATLAS_MCP_TOKEN through your client secret store or secure environment before connecting.

Operator environment

ATLAS_MCP_ALLOWED_ORIGINS=https://approved-client.example
ATLAS_MCP_RATE_LIMIT=60

03 · Workflow

Search first. Retrieve second.

This keeps agent context focused and lets the result itself supply the exact identifier for the next call.

01

Read the catalogue

Open atlas://catalog when the agent needs dataset counts, entry types, lookup examples or source status.
02

Narrow the search

Call search_atlas with a product, region or currency wherever possible.
03

Reuse identifiers

Pass the exact type and identifier returned by search into get_atlas_entry.
04

Start with summary

Request detail: complete only when all available nested source detail is required.
05

Check provenance

Read data_status and the disclaimer before using a result in solution design.

Search tip: every free-text search word must match the same record. Use the dedicated region and currency filters instead of placing every constraint in query.

04 · Tools and resource

A deliberately small interface.

Two read-only tools cover discovery and exact retrieval. One resource explains the catalogue itself.

Tool · Search

search_atlas

Searches all or one product area and returns bounded summaries with identifiers for exact retrieval.

Parameter	Accepted values	Details
query	String, up to 120 characters	Matches names, codes, rails, methods, schemes, capabilities and use cases.
product	all, payouts, fund-and-collect, card-issuance, fx	Optional. Defaults to all.
region	String, up to 80 characters	For example Europe or Asia.
currency	Three ASCII letters	For example USD, EUR or ZAR.
limit	1 to 25	Optional. Defaults to 10.

Returns applied filters, total matches, returned count, truncation state, result items, data status and the shared disclaimer.

Tool · Retrieve

get_atlas_entry

Retrieves one exact record using a type and identifier returned by search.

Parameter	Accepted values	Details
type	payout-country, funding-currency, card-market, fx-pair	Required. Reuse the value returned by search.
identifier	Exact identifier, name or code	Required. FX pairs use USD/EUR or USD-EUR. Maximum 120 characters.
detail	summary, complete	Optional. Defaults to summary. Complete payout records can be large.

JSON resource

atlas://catalog

Describes product datasets, current entry counts, lookup examples, source status and the recommended retrieval workflow.

Schema 1.0

05 · Usage examples

Ask naturally. Inspect precisely.

Your agent can translate a clear request into tool arguments. These examples also show the exact JSON when you need deterministic control.

Example 01 · Payouts

Find real-time B2B payout markets.

Use Nium Atlas to find European payout markets that support real-time B2B payouts. Return no more than five results and include each Atlas record link.

search_atlas arguments

{
  "query": "realtime B2B",
  "product": "payouts",
  "region": "Europe",
  "limit": 5
}

get_atlas_entry arguments

{
  "type": "payout-country",
  "identifier": "united-kingdom",
  "detail": "summary"
}

Example 02 · Card issuing

Find markets for a currency.

Search Atlas for card issuing markets that support ZAR. Keep the result limited to ten markets and explain the source status.

search_atlas arguments

{
  "product": "card-issuance",
  "currency": "ZAR",
  "limit": 10
}

Example 03 · FX

Inspect one currency pair.

Retrieve the Atlas summary for USD to EUR. Report settlement behaviour, use cases and weekend support.

get_atlas_entry arguments

{
  "type": "fx-pair",
  "identifier": "USD/EUR",
  "detail": "summary"
}

Example 04 · Complete detail

Retrieve nested payout data.

Retrieve the complete United States payout entry. Separate methods, currencies, delivery speeds, client types and account verification support. Keep the Atlas disclaimer visible.

get_atlas_entry arguments

{
  "type": "payout-country",
  "identifier": "US",
  "detail": "complete"
}

06 · Data status

Reference data, not availability confirmation.

Every successful data response includes data_status, authoritative: false and a plain-language disclaimer.

payout-country

Payouts

227 entries

Status: Imported reference snapshot
Source: Application database

Not authoritative

funding-currency

Fund & Collect

10 entries

Status: Representative fixture
Source: Application fixtures

Not authoritative

card-market

Card Issuing

7 entries

Status: Imported reference snapshot
Source: Application database

Not authoritative

fx-pair

FX

10 entries

Status: Representative fixture
Source: Application fixtures

Not authoritative

Required interpretation

Payout and card issuance data use imported reference snapshots. Fund & Collect and FX data are representative. Confirm production availability before implementation.

Imported reference snapshot: data was imported into the application database from a source snapshot.

Representative fixture: representative application content that should not be interpreted as complete coverage.

07 · Security

Read-only by design.

The server is intentionally narrow. It reads through application repository contracts and does not write catalogue data.

Tool safety

Both tools are marked read-only, idempotent, non-destructive and closed world.
HTTP ability

Every HTTP request requires a Bearer token with the mcp:read ability.
Origin control

Browser requests must come from an origin in ATLAS_MCP_ALLOWED_ORIGINS.
Rate limit

HTTP traffic is limited by IP. The default is 60 requests per minute.
Protocol guard

Unsupported MCP-Protocol-Version values are rejected before tool execution.
Secret handling

Use HTTPS remotely and keep tokens outside source control, page source, logs and prompts.

Endpoint distinction: the generic BusinessPress /mcp server is separate. Atlas clients must use /mcp/atlas.

08 · Troubleshooting

Start with the visible symptom.

Symptom	What to check
Server does not appear	Use absolute paths for PHP and artisan, confirm Composer dependencies are installed, then run the MCP Inspector command.
401 invalid_token	The HTTP token is missing, malformed, expired or revoked.
403 Forbidden	The token may lack mcp:read, or the browser Origin is not allowlisted. Read the response message.
400 protocol version	Update the MCP client or use one of the protocol versions returned in the error response.
429 Too Many Requests	Wait for the Retry-After period and reduce request frequency.
No entry matched	Call search_atlas first and reuse its type and identifier exactly.
FX identifier rejected	Use exactly three letters per currency, for example USD/EUR or USD-EUR.
Response is too large	Keep detail at summary, narrow the search and lower the limit.
Results look incomplete	Check data_status. Representative fixtures are not complete coverage.
Imported data looks stale	An authorised maintainer can rerun the payout and card issuing import commands, then clear application caches.

09 · FAQ

Useful before you connect.

Does Atlas MCP change data?

No. The current tools only search and retrieve data.

Does it call an AI model?

No. Atlas MCP exposes deterministic repository data. The connected client supplies the agent and model.

Do I need a token locally?

No for STDIO. Every Streamable HTTP request requires a scoped Bearer token.

Can I open the endpoint as a normal webpage?

No. /mcp/atlas is a machine transport. This page is the human-readable setup guide.

Does a result confirm current Nium availability?

No. Check the source status, then confirm production availability before implementation or customer commitments.

Which clients can connect?

Any MCP-compatible client that supports local STDIO or Streamable HTTP and can negotiate a protocol version supported by the server.

Framework reference

Laravel MCP documentation

Protocol reference

MCP transport specification

Give your AI agent a structured view of Atlas.

One interface for four Atlas product areas.

Payouts

Fund & Collect

Card Issuing

FX

Choose how your client connects.

STDIO

Streamable HTTP

Prepare the local application.

Connect with STDIO.

Connect over Streamable HTTP.

Search first. Retrieve second.

Read the catalogue

Narrow the search

Reuse identifiers

Start with summary

Check provenance

A deliberately small interface.

search_atlas

get_atlas_entry

atlas://catalog

Ask naturally. Inspect precisely.

Find real-time B2B payout markets.

Find markets for a currency.

Inspect one currency pair.

Retrieve nested payout data.

Reference data, not availability confirmation.

Payouts

Fund & Collect

Card Issuing

FX

Read-only by design.

Tool safety

HTTP ability

Origin control

Rate limit

Protocol guard

Secret handling

Start with the visible symptom.

Useful before you connect.