Get started
Run the ATP MCP server locally, configure it, and connect an MCP client.
Not deployed
This page walks through running the ATP MCP server on your machine and connecting a client. There is no hosted server yet, so everything here is local. For what the server does, read the overview first.
Prerequisites
| You need | Detail |
|---|---|
| Node.js | Version 22 or newer. |
| An OAuth 2.1 authorization server | It issues RFC 9068 JWT access tokens signed with an asymmetric algorithm, publishes an https key set (JWKS), and can set the token audience to this server's resource URL. The MCP server does not issue tokens. See Authorization. |
| A chain RPC URL | An https BSC Testnet (chain id 97) endpoint. The server only reads. |
| An application backend (optional) | Needed for five of the six tools. None exists yet, so those tools answer BLOCKED_INTEGRATION. |
Install and run
npm ci
npm run typecheck
npm test
npm run build
cp .env.example .env # placeholders only; never commit .env
node --env-file=.env dist/main.jsThe server does not read a .env file by itself. The --env-file flag loads it. On startup it prints one redacted configuration line and a listening line. An invalid variable stops the process with an error that names the variable and never its value. The default address is 127.0.0.1:8080.
Quick checks once it runs:
| Request | Expected answer |
|---|---|
GET /healthz | 200 {"status":"ok"} |
GET /.well-known/oauth-protected-resource/mcp | 200 JSON with resource, authorization_servers and scopes_supported |
POST /mcp with no token | 401 with a WWW-Authenticate: Bearer resource_metadata="..." challenge |
Requests whose Host header is not in ATP_MCP_ALLOWED_HOSTS get 403 HOST_NOT_ALLOWED. When you test with curl localhost, send an allowed Host header.
Configuration
Every variable starts with ATP_MCP_. Values are trimmed, and an empty value counts as unset. Validation fails closed at startup.
| Variable | Required | Purpose |
|---|---|---|
ATP_MCP_RESOURCE_URL | Yes | Public URL of the MCP endpoint. It is also the required token audience. |
ATP_MCP_AUTH_ISSUER | Yes | The exact iss your tokens carry. |
ATP_MCP_AUTH_JWKS_URL | Yes | https URL of the key set used to verify tokens. |
ATP_MCP_RPC_URL | Yes | https chain RPC URL. Treat it as a secret if it carries a key. |
ATP_MCP_LOG_SUBJECT_SALT | Yes | Secret of 16 or more characters used to pseudonymise subjects in audit logs. |
ATP_MCP_CLIENTS | No | JSON registry of client ids and their application. Empty means every token is denied. |
ATP_MCP_AUTH_ALGORITHMS | No | Allowed signature algorithms. Default ES256,RS256,EdDSA. |
ATP_MCP_ALLOWED_HOSTS | No | Accepted Host values. Defaults to the host of the resource URL. |
ATP_MCP_ALLOWED_ORIGINS | No | Browser origins allowed to call the endpoint. Default none. |
ATP_MCP_MAX_BODY_BYTES | No | Request body limit. Default 65536. |
ATP_MCP_SINERA_BACKEND_URL and ATP_MCP_SINERA_BACKEND_TOKEN | No | Set together to point at a Sinera backend. |
ATP_MCP_DASHBOARD_BACKEND_URL and ATP_MCP_DASHBOARD_BACKEND_TOKEN | No | Same for the Developer Portal. |
ATP_MCP_PREFLIGHT_ENABLED_APPS | No | Applications allowed to run the preflight tool. Default empty (off). |
ATP_MCP_EXECUTION_ENABLED_APPS | No | Applications allowed to run the execution tool. Default empty (off). |
ATP_MCP_RATE_LIMIT_PER_MINUTE | No | Per-caller token bucket. Default 60. |
ATP_MCP_HOST and ATP_MCP_PORT | No | Listen address and port. |
The registry has this shape:
{ "my-client": { "application": "sinera" } }Keep the gates off
Leave the preflight and execution variables empty, and leave the backend pairs unset, unless you run a backend that implements the adapter API. Four values are secrets and belong in a secret manager: the RPC URL when it carries a key, both backend tokens, and the subject salt.
Connect a client
Any client that speaks MCP 2026-07-28 over Streamable HTTP can connect. Clients that open with the older initialize handshake are refused with HTTP 400 and JSON-RPC error -32022.
- The client sends a request to the MCP endpoint with no token.
- The server answers
401with a challenge that points at its protected resource metadata (RFC 9728). - The client reads
authorization_serversfrom that document and discovers your authorization server. - The client gets an access token (authorization code with PKCE, resource set to the server's URL, scopes among
atp:read,atp:preflightandatp:execute) and sends it asAuthorization: Bearer <token>on every request.
A TypeScript client using the official SDK:
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
const client = new Client(
{ name: "my-client", version: "1.0.0" },
{ versionNegotiation: { mode: { pin: "2026-07-28" } } },
);
await client.connect(
new StreamableHTTPClientTransport(new URL("https://mcp.example.org/mcp"), {
requestInit: { headers: { authorization: `Bearer ${accessToken}` } },
}),
);
const { tools } = await client.listTools(); // the same six tools for every callerThe discovery flow has not been tried against a real authorization server.
Make a first call
atp_get_atom needs only atp:read and no backend:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "atp_get_atom",
"arguments": {
"chainId": 97,
"atomCore": "0x<pinned AtomCore address>",
"atomId": "0x<32-byte atom id>"
}
}
}The server accepts only the pinned chain and the pinned AtomCore address. Any other deployment returns UNSUPPORTED_DEPLOYMENT before a chain call. A successful result has status: "FOUND", the Atom facts, and evidence. See the Tool reference for every field.