MCP Guide

Purpose

This guide explains how to use Norynta MCP servers safely and effectively for tool-using AI assistants and agent runtimes.

Audience

AI assistant operators integrating MCP tools
engineering teams evaluating tool-based workflows
operators wiring Norynta MCP into local or hosted assistants

MCP server map

Norynta provides a hosted gateway plus three local MCP servers:

Hosted remote MCP (https://norynta-mcp.vercel.app/mcp)
- best default for hosted agents and assistants; no repository checkout required
- Streamable HTTP transport
- combines public discovery, market data, validation, and signed execution tools
- keep host approval enabled for orders_place and orders_cancel
Public MCP (npm run mcp-public)
- best for discovery, diagnostics, and read/simulate-first market intelligence
- tools: agent_bootstrap, market_search, events_top, events_snapshots, agent_access, validate_trade, estimate_impact, developer_diagnostics, explain_failed_request, integration_compatibility
Trading MCP (npm run mcp-trading)
- for first-trade checks and signed execution requests
- tools: orders_place, orders_cancel, orders_my
- expects caller-supplied wallet-signature headers for write paths
- requires caller-supplied idempotency keys for mutating tools
Ops MCP (npm run mcp-ops)
- for local environment and MCP wiring checks
- tools: ops_get_env_status, ops_get_mcp_status

Quick start

For a hosted MCP client, add this server URL directly:

https://norynta-mcp.vercel.app/mcp

OpenAI Responses API tool configuration:

{
  "type": "mcp",
  "server_label": "norynta",
  "server_url": "https://norynta-mcp.vercel.app/mcp",
  "require_approval": "always"
}

After reviewing tool annotations, clients may allow read-only tools without approval while continuing to require approval for write tools. Pass a scoped agent token through the client's MCP authorization or headers configuration.

For local stdio clients:

Ensure app/API is available locally or remotely.
Start the desired MCP server (for example, public):

npm run mcp-public

Validate server registration and tool listing:

npm run mcp:smoke

The smoke check starts all three servers concurrently, verifies tool metadata and safety annotations, and executes a structured read-only ops tool.

Use the .mcp.json template for client configuration.

Server selection guidance

Use hosted remote MCP when the AI runtime accepts a Streamable HTTP URL.
Use public MCP for read-only bots and assistant discovery tools. Start with agent_bootstrap; it fetches discovery, access, policy, protocol, and compatibility metadata concurrently in one round trip.
Use trading MCP only for flows that already implement signing, idempotency, retries, and policy-aware write controls.
Use ops MCP for operator workflows and local validation.

Safety boundaries

Treat MCP tools as convenience wrappers over HTTP contracts, not a replacement for execution guardrails.
Keep trading credentials scoped and rotated.
Apply deterministic IDs (clientOrderId / idempotency-key) on writes.
Simulate before placing aggressive flow.
Reconcile stream gaps with periodic snapshots.
Prefer least-privilege keys and endpoint allowlists where available.

Environment and auth notes

MCP requests use the same backend base URL resolution as runtime scripts.
Set NORYNTA_AGENT_API_KEY (or legacy NORYNTA_API_KEY) once; MCP HTTP calls automatically send both Bearer and compatibility API-key headers.
HTTP calls are cancellation-aware, cap response size, and default to a 10-second per-attempt timeout. Tune with NORYNTA_MCP_TIMEOUT_MS and NORYNTA_MCP_MAX_RESPONSE_BYTES when needed.
Trading tools require valid wallet signature headers for authenticated writes.
Some discovery surfaces may return richer metadata when API keys are supplied.
Server-to-server remote MCP clients normally omit Origin. Browser-origin calls are restricted to Norynta and supported assistant hosts.

Related docs

docs/public/INTEGRATION_START_HERE.md
docs/public/SDK_AND_EXAMPLES.md
docs/AGENT_INTEGRATION.md
.mcp.json