Skip to content
SineraDocs

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 needDetail
Node.jsVersion 22 or newer.
An OAuth 2.1 authorization serverIt 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 URLAn 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.js

The 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:

RequestExpected answer
GET /healthz200 {"status":"ok"}
GET /.well-known/oauth-protected-resource/mcp200 JSON with resource, authorization_servers and scopes_supported
POST /mcp with no token401 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.

VariableRequiredPurpose
ATP_MCP_RESOURCE_URLYesPublic URL of the MCP endpoint. It is also the required token audience.
ATP_MCP_AUTH_ISSUERYesThe exact iss your tokens carry.
ATP_MCP_AUTH_JWKS_URLYeshttps URL of the key set used to verify tokens.
ATP_MCP_RPC_URLYeshttps chain RPC URL. Treat it as a secret if it carries a key.
ATP_MCP_LOG_SUBJECT_SALTYesSecret of 16 or more characters used to pseudonymise subjects in audit logs.
ATP_MCP_CLIENTSNoJSON registry of client ids and their application. Empty means every token is denied.
ATP_MCP_AUTH_ALGORITHMSNoAllowed signature algorithms. Default ES256,RS256,EdDSA.
ATP_MCP_ALLOWED_HOSTSNoAccepted Host values. Defaults to the host of the resource URL.
ATP_MCP_ALLOWED_ORIGINSNoBrowser origins allowed to call the endpoint. Default none.
ATP_MCP_MAX_BODY_BYTESNoRequest body limit. Default 65536.
ATP_MCP_SINERA_BACKEND_URL and ATP_MCP_SINERA_BACKEND_TOKENNoSet together to point at a Sinera backend.
ATP_MCP_DASHBOARD_BACKEND_URL and ATP_MCP_DASHBOARD_BACKEND_TOKENNoSame for the Developer Portal.
ATP_MCP_PREFLIGHT_ENABLED_APPSNoApplications allowed to run the preflight tool. Default empty (off).
ATP_MCP_EXECUTION_ENABLED_APPSNoApplications allowed to run the execution tool. Default empty (off).
ATP_MCP_RATE_LIMIT_PER_MINUTENoPer-caller token bucket. Default 60.
ATP_MCP_HOST and ATP_MCP_PORTNoListen 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.

  1. The client sends a request to the MCP endpoint with no token.
  2. The server answers 401 with a challenge that points at its protected resource metadata (RFC 9728).
  3. The client reads authorization_servers from that document and discovers your authorization server.
  4. The client gets an access token (authorization code with PKCE, resource set to the server's URL, scopes among atp:read, atp:preflight and atp:execute) and sends it as Authorization: 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 caller

The 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.