Skip to main content
Wire any agent — any language, any framework — to the Nasiko MCP gateway so it can discover and call every tool a user has connected, with zero hardcoded tool names. If your agent runs on Nasiko, it doesn’t need an MCP SDK, a special client library, or any per-connector code. It needs two environment variables that Nasiko injects at deploy time, one header it forwards, and one small tool-calling loop. This page covers that, in whatever framework you’re already using — LangChain, LangGraph, CrewAI, Google ADK, the raw OpenAI SDK, Anthropic’s SDK, or a hand-rolled agent in Node, Rust, or Go.
For the router to work, each agent is given two environment variables at deploy time: OPENAI_BASE_URL (the gateway’s address, not api.openai.com) and OPENAI_API_KEY — not a real provider key, but a signed ticket that says “I am agent X, acting on behalf of user Y.” Your agent framework already reads both of these to construct its LLM client, so most of the wiring is already done for you — this page is about the tool-calling half, not the LLM half.
A complete working example is the general-assistant agent, agents/general-assistant-1.1.1.zip in the nasiko repo. It’s a Python a2a-sdk agent that uses whatever MCP tools it’s granted, asks the user instead of guessing, and pauses for tool approvals. Deploy it with nasiko upload agents/general-assistant-1.1.1.zip, then send hitl input test, hitl auth test, hitl options test, or hitl multiselect test to check the approval wiring without a model key.

How it works

Every tool call your agent makes goes through one HTTP endpoint — MCP_GATEWAY_URL — using plain JSON-RPC 2.0. There is no MCP client SDK dependency: you POST a JSON body and read a JSON body back. The two methods you need are tools/list (what’s available right now, for this agent) and tools/call (invoke one). The gateway checks two things on each call, and they travel separately: The gateway looks up the user from the request named by the traceparent, and allows a tools/call only when your agent is part of that request. What the call may do is the intersection of that user’s connections and your agent’s tool permissions. tools/list needs only the agent credential, so your agent can discover tools at startup, outside any request.
MCP_GATEWAY_TOKEN is a secret. Never log it, never return it to a user, and never send it anywhere except the gateway. Redeploying the agent replaces it, and deleting the agent revokes it.

Quickstart

1

Read the gateway URL and token

Both are injected into your agent’s environment at deploy time. MCP_GATEWAY_URL already includes the full path. If either is empty, your agent was deployed without the gateway enabled, or before it was — skip tool-calling gracefully rather than erroring out.
Some framework MCP clients accept only a URL, with no way to set a header. For those, use MCP_GATEWAY_CONNECT_URL instead: the same endpoint with the credential in the path. Treat that URL as a secret too. Prefer the header form when your client supports it.
2

Read the inbound traceparent

Every request that reaches your agent carries a traceparent header. Read it from the request you’re serving, using whatever your framework exposes for inbound headers, and forward that exact value on every gateway call you make while serving it.
Two things to watch for, both seen in practice:
  • Read it per request. With a2a-sdk, a resumed task runs on the worker created by the original request, so a value stored in a context variable is stale. Read it inside execute() from context.call_context.state["headers"]["traceparent"].
  • Don’t let OpenTelemetry replace it. httpx auto-instrumentation overwrites traceparent on outbound calls with the current span’s value, and the gateway rejects the call with 403. Suppress instrumentation for the gateway request only:
No traceparent? tools/list still works, but tools/call is rejected. Skip tool calls for this request — don’t crash.
3

Call the gateway

One helper function covers both methods you’ll ever need.
Never hardcode tool names — they depend on what the user has connected and change whenever a connector is added or removed. Always call tools/list fresh. See Protocol reference for exact request and response shapes.
4

Merge into your LLM's tool list

Add two function-calling tools alongside whatever tools your agent already has — don’t replace them.
Dispatch by name in whatever tool-execution code you already have — one branch, nothing else changes:
Each tools/list entry has a name, a description, and an inputSchema (JSON Schema), so you can also map the list one-to-one onto native function-tool definitions instead of using the two wrapper tools.Name collision with a tool you already have? Rename either side — there’s no fixed contract, mcp_list_tools and mcp_call_tool are just this page’s convention.LLMs tend to refuse a tool instead of trying it when they’re not 100% sure it’s relevant. Push back in your system prompt:
“Always call mcp_list_tools first. If any tool plausibly relates to the request, call it with best-effort arguments — don’t ask for clarification, don’t skip it because you’re unsure. Only say nothing’s available after actually trying.”
5

Bound the loop and handle timeouts

If you’re not using a framework with a built-in agent loop, cap the manual one and make sure a mid-loop cutoff doesn’t silently drop results.
Use 30–60s or longer timeouts for gateway calls, not a short default — real connectors (Notion, Slack, and the like) can be genuinely slow. A caught-but-unmessaged timeout often logs as an empty string and looks to the user like a silent crash.If you’re using LangChain, LangGraph, CrewAI, or Google ADK, skip this step entirely — see Framework integrations below, your framework already runs this loop for you.

Protocol reference

Plain JSON-RPC 2.0 over a single endpoint (MCP_GATEWAY_URL), always POST.
  • Credential and request checks fail with an HTTP status: 401 when the Bearer credential is missing, unknown, revoked, or belongs to a deleted agent; 403 when a tools/call has no traceparent, names a request that has finished, or names a request your agent isn’t part of. All of these fail closed.
  • Everything else returns HTTP 200. A failed tool call is a JSON-RPC error object in the body.

Methods

Error codes

For -32001 and -32002, error.data carries the gateway’s approval request ID: hitl_request_id, or hitl_request_ids (a list) for a batched call such as Composio’s COMPOSIO_MULTI_EXECUTE_TOOL. Read both keys, and include the ID when you pause so approving the request grants the tool.

Framework integrations

Pick your framework. In every case, the pattern is the same: wrap the two gateway calls as tools your framework already knows how to call, and add them to whatever tool list you already have. traceparent below is the value you read in Quickstart step 2 for the current request.

LangChain

LangGraph

mcp_list_tools and mcp_call_tool are the same @tool-decorated functions from the LangChain section above — LangGraph’s prebuilt ReAct agent accepts the same tool objects.

CrewAI

Same pattern as LangChain: wrap the two functions as @tool-decorated CrewAI tools, add them to the agent’s tools list, and set max_iter on the agent to bound the loop.

Google ADK

ADK derives a tool’s schema from a plain Python function’s type hints and docstring — no decorator needed, just pass the functions directly:

OpenAI Agents SDK and raw SDK

See Quickstart above — the manual loop shown there is the raw-SDK pattern. If you’re on the OpenAI Agents SDK specifically, wrap the two functions with @function_tool and add them to your Agent’s tools list the same way; the SDK’s own Runner loop handles the rest.

Anthropic Claude (native tool use)

Claude’s native tool-use format isn’t OpenAI-compatible: the schema field is input_schema (not parameters), and tool results go back as a tool_result content block, not a role: tool message.

Node.js and TypeScript

No SDK dependency needed — a raw fetch call works with any Node framework or agent library:

Rust

Local testing

Test tools/list with curl before wiring up any agent code — this isolates “are my URL and credential correct” from “is my agent code correct.” It needs no traceparent.
A non-empty result.tools array means your URL and credential are both correct — any remaining problem is in your agent code, not the gateway. HTTP 401 means the credential is wrong, revoked, or from an earlier deploy; read it from the running container’s environment again. tools/call can’t be tested this way: it only works while your agent is serving a real request. Send the agent a message from the dashboard or nasiko chat instead.

Security

  • Never log MCP_GATEWAY_TOKEN or MCP_GATEWAY_CONNECT_URL — log token present: true/false only.
  • Never forward the token to a third-party service, or echo it back to the end user in a response.
  • The token alone can’t call tools for a user. A tools/call also needs a live request that your agent is part of, so a leaked token can’t be replayed outside one.
  • Redeploying the agent issues a new token. The previous one keeps working for 15 minutes so a slow rollout doesn’t fail. Deleting the agent revokes it.

Troubleshooting

Checklist

Before calling your integration done, verify each of these against a real deployment:
  • MCP_GATEWAY_URL or MCP_GATEWAY_TOKEN missing — agent still answers plain questions, no crash
  • traceparent missing — tool calls skipped gracefully
  • tools/list returns tools when the user has a connector configured
  • tools/call result reaches the LLM and is used in the final answer
  • An ask tool pauses the task for approval instead of failing
  • No connector for the topic — an honest “nothing available,” never a made-up answer
  • A bad tool call reports the real error, with no silent fallback to something else
  • A slow tool produces a clean timeout message, not a blank crash
  • Pre-existing tools still work unchanged, and the LLM can call one of yours and one gateway tool in the same turn