Connect your agent to the MCP gateway

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 exactly two things at deploy time, 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.

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 user, for this agent) and tools/call (invoke one). Authentication is a single header, x-nasiko-agent-token — a short-lived, per-request credential minted by the platform and forwarded to your agent on every inbound call. You read it once, and forward the exact same value on every outbound call you make to the gateway during that request.

This token is not your agent’s static API key. It’s minted fresh per inbound request and expires in minutes. Never cache it across requests, never log its full value, and never forward it anywhere except the gateway.

Quickstart

Read the gateway URL

Injected automatically into your agent’s environment at deploy time — already includes the full path. If it’s empty, your agent either isn’t deployed with the gateway enabled, or was deployed before it was — skip tool-calling gracefully rather than erroring out.

MCP_GATEWAY_URL = os.environ.get("MCP_GATEWAY_URL", "")  # already includes /api/mcp

Read the inbound delegation token

Every request that reaches your agent carries x-nasiko-agent-token as a header. Pull it out using whatever your framework exposes for inbound headers.

def get_token(context: RequestContext) -> str | None:
    call_context = context.call_context
    if not call_context:
        return None
    return call_context.state.get("headers", {}).get("x-nasiko-agent-token")

from fastapi import Request

async def handler(request: Request):
    token = request.headers.get("x-nasiko-agent-token")

from flask import request

token = request.headers.get("x-nasiko-agent-token")

app.post("/", (req, res) => {
  const token = req.headers["x-nasiko-agent-token"];
});

token := r.Header.Get("X-Nasiko-Agent-Token")

If your framework doesn’t expose inbound headers anywhere in the handler context, wrap it in middleware that copies them somewhere your handler can reach:

class TokenMiddleware:
    def __init__(self, app): self.app = app
    async def __call__(self, scope, receive, send):
        if scope["type"] == "http":
            headers = dict(scope["headers"])
            scope["state"]["mcp_token"] = headers.get(b"x-nasiko-agent-token", b"").decode() or None
        await self.app(scope, receive, send)

No token present? Skip tool access for this request — don’t crash.

Call the gateway

One helper function covers both methods you’ll ever need.

async def mcp_call(method: str, params: dict | None, token: str) -> dict:
    body = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": method}
    if params is not None:
        body["params"] = params
    async with httpx.AsyncClient(timeout=60.0) as client:
        resp = await client.post(MCP_GATEWAY_URL, headers={"x-nasiko-agent-token": token}, json=body)
        return resp.json()

Never hardcode tool names — they’re per-user and change whenever a connector is added or removed. Always call tools/list fresh. See Protocol reference for exact request and response shapes.

Merge into your LLM's tool list

Add two function-calling tools alongside whatever tools your agent already has — don’t replace them.

tool_defs = existing_tools + [
    {"type": "function", "function": {"name": "mcp_list_tools", "description": "List available MCP tools.", "parameters": {"type": "object", "properties": {}}}},
    {"type": "function", "function": {"name": "mcp_call_tool", "description": "Call an MCP tool by exact name from mcp_list_tools.", "parameters": {"type": "object", "properties": {
        "tool_name": {"type": "string"}, "arguments": {"type": "object"}
    }, "required": ["tool_name"]}}},
]

Dispatch by name in whatever tool-execution code you already have — one branch, nothing else changes:

if call.function.name == "mcp_list_tools":
    result = await mcp_call("tools/list", None, token)
elif call.function.name == "mcp_call_tool":
    args = json.loads(call.function.arguments)
    result = await mcp_call("tools/call", {"name": args["tool_name"], "arguments": args.get("arguments", {})}, token)
else:
    result = run_my_existing_tool(call)  # unchanged

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

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.

for _ in range(10):                       # cap the loop
    resp = await llm.chat.completions.create(model=model, messages=messages, tools=tool_defs)
    choice = resp.choices[0].message
    messages.append(choice.model_dump(exclude_none=True))
    if not choice.tool_calls:
        return choice.content
    for call in choice.tool_calls:
        result = dispatch(call)           # your logic from the previous step
        messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

# hit cap mid-tool-use: don't drop results, force a final answer
messages.append({"role": "user", "content": "Stop calling tools. Summarize what you found."})
return (await llm.chat.completions.create(model=model, messages=messages)).choices[0].message.content

try:
    result = await mcp_call(...)
except httpx.TimeoutException:
    return "That tool call took too long and was cancelled."

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, always HTTP 200 — a failed tool call is a JSON-RPC error object in the body, not an HTTP error status.

Methods

Method	Params	Result	Notes
`initialize`	—	Handshake info	Optional. Only needed if wrapping the gateway in a real MCP client SDK — skip it if calling the gateway directly as shown above.
`ping`	—	`{}`	Optional liveness check.
`tools/list`	—	`{"tools": [{"name", "description", "inputSchema"}]}`	Per-user, per-agent. Changes any time the user connects or disconnects a service, or your agent’s permissions change. Always fetch fresh — never cache across turns or sessions.
`tools/call`	`{"name", "arguments"}`	`{"content": [...], "isError": bool}` or `{"error": {"code", "message"}}`	`name` must be the exact namespaced string from `tools/list` (`connectorId__toolName`) — treat it as opaque, never construct it yourself.

Error codes

Code	Meaning	What your agent should do
`-32000`	Blocked by the user’s own permission rules	Tell the user it’s blocked. Don’t retry, don’t silently substitute a different tool.
`-32001`	Needs human approval (an “ask”-stance tool)	Tell the user approval is pending. Don’t retry-loop.
`-32602`	Missing or invalid delegation token	A bug in your own header forwarding — not user-facing.
`-32601`	Unknown method	Check your `method` string.
Any other	A real failure from the underlying service	Report it honestly. Never fake success, never silently swap in a fallback the user didn’t ask for.

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.

LangChain

from langchain_core.tools import tool

@tool
async def mcp_list_tools() -> dict:
    """List available MCP tools."""
    return await mcp_call("tools/list", None, token)

@tool
async def mcp_call_tool(tool_name: str, arguments: dict) -> dict:
    """Call an MCP tool by exact name from mcp_list_tools."""
    return await mcp_call("tools/call", {"name": tool_name, "arguments": arguments}, token)

agent_executor = AgentExecutor(
    agent=agent,
    tools=existing_tools + [mcp_list_tools, mcp_call_tool],
    max_iterations=10,                 # = the loop cap
    early_stopping_method="generate",  # = force a final answer instead of dropping results
)

LangGraph

from langgraph.prebuilt import create_react_agent

graph = create_react_agent(model, tools=existing_tools + [mcp_list_tools, mcp_call_tool])
result = await graph.ainvoke({"messages": [...]}, config={"recursion_limit": 10})  # = the loop cap

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:

from google.adk.agents import Agent

async def mcp_list_tools() -> dict:
    """List available MCP tools."""
    return await mcp_call("tools/list", None, token)

async def mcp_call_tool(tool_name: str, arguments: dict) -> dict:
    """Call an MCP tool by exact name from mcp_list_tools.

    Args:
        tool_name: Exact namespaced tool name from mcp_list_tools.
        arguments: Arguments object for the tool call.
    """
    return await mcp_call("tools/call", {"name": tool_name, "arguments": arguments}, token)

root_agent = Agent(
    model="gemini-2.0-flash",
    tools=existing_tools + [mcp_list_tools, mcp_call_tool],
)

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.

tool_defs = existing_tools + [
    {"name": "mcp_list_tools", "description": "List available MCP tools.", "input_schema": {"type": "object", "properties": {}}},
    {"name": "mcp_call_tool", "description": "Call an MCP tool by exact name.", "input_schema": {"type": "object", "properties": {
        "tool_name": {"type": "string"}, "arguments": {"type": "object"}
    }, "required": ["tool_name"]}},
]

for block in response.content:
    if block.type == "tool_use":
        result = dispatch_by_name(block.name, block.input)   # same dispatch logic as the Quickstart
        messages.append({"role": "user", "content": [
            {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(result)}
        ]})

Node.js and TypeScript

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

async function mcpCall(method: string, params: object | null, token: string) {
  const body = { jsonrpc: "2.0", id: crypto.randomUUID(), method, ...(params ? { params } : {}) };
  const resp = await fetch(process.env.MCP_GATEWAY_URL!, {
    method: "POST",
    headers: { "x-nasiko-agent-token": token, "Content-Type": "application/json" },
    signal: AbortSignal.timeout(60_000),
    body: JSON.stringify(body),
  });
  return resp.json();
}

Rust

async fn mcp_call(client: &reqwest::Client, gateway_url: &str, method: &str, params: Option<Value>, token: &str) -> Value {
    let mut body = json!({ "jsonrpc": "2.0", "id": Uuid::new_v4().to_string(), "method": method });
    if let Some(p) = params {
        body["params"] = p;
    }
    client
        .post(gateway_url)
        .header("x-nasiko-agent-token", token)
        .timeout(std::time::Duration::from_secs(60))
        .json(&body)
        .send()
        .await
        .and_then(|r| r.json::<Value>())  // handle the Result properly in real code
        .unwrap_or_else(|e| json!({ "error": { "message": e.to_string() } }))
}

Local testing

Test with curl before wiring up any agent code — this isolates “is my token and URL correct” from “is my agent code correct.”

curl -s -X POST "$MCP_GATEWAY_URL" \
  -H "x-nasiko-agent-token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | jq

A non-empty result.tools array means your token and URL are both correct — any remaining problem is in your agent code, not the gateway. A -32602 means your token is invalid, expired, or missing; grab a fresh one from a real inbound request rather than reusing an old value.

Security

Never log the full token value — 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.
Never cache or persist the token — it’s minted fresh per inbound request and expires in minutes by design.
The token is the only credential this endpoint accepts. There’s no separate API key to rotate or manage.

Troubleshooting

Symptom	Likely cause
`tools/list` returns an empty array	Not a bug — the user has no connectors configured yet, or none granted to this specific agent. Check the connector settings.
Every gateway call returns `-32602`	Token isn’t being forwarded correctly, or you’re reading the wrong header. Double-check you’re reading `x-nasiko-agent-token` exactly.
Agent works, then randomly “loses” tool access mid-session	You’re caching the token across requests — re-read it from the inbound request every time.
Agent ignores an obviously relevant tool	System prompt isn’t pushing the model hard enough to try tools — see the prompt guidance in Quickstart step 4.
Blank or empty error message on a slow request	Timeout too short, or the exception isn’t caught explicitly — see Quickstart step 5.
Agent answers using stale or wrong tool names	Tool list is being cached — always call `tools/list` fresh, every turn.
`MCP_GATEWAY_URL` is empty in production	Agent was deployed before the gateway was enabled for it — redeploy, a restart alone won’t pick up newly injected environment variables.

Checklist

Before calling your integration done, verify each of these against a real deployment:

MCP_GATEWAY_URL missing — agent still answers plain questions, no crash
Token missing — same, graceful skip
tools/list returns tools when the user has a connector configured
tools/call result reaches the LLM and is used in the final answer
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

Connect an external MCP server — register a managed toolkit or your own already-running MCP server as a connector your agents can use
Per-agent tool permissions — control which connectors and tools an agent may call
A2A agents and frameworks — how agents themselves are invoked and discovered on the platform
Agent development lifecycle — end-to-end: scaffold, build, deploy, and version an agent

Getting Started

CLI

ADLC

Dashboard

Platform

MCP Gateway

MCP Hub

Agents in Artifact Registry

Connect your agent to the MCP gateway

How it works

Quickstart

Protocol reference

Methods

Error codes

Framework integrations

LangChain

LangGraph

CrewAI

Google ADK

OpenAI Agents SDK and raw SDK

Anthropic Claude (native tool use)

Node.js and TypeScript

Rust

Local testing

Security

Troubleshooting

Checklist

​How it works

​Quickstart

​Protocol reference

​Methods

​Error codes

​Framework integrations

​LangChain

​LangGraph

​CrewAI

​Google ADK

​OpenAI Agents SDK and raw SDK

​Anthropic Claude (native tool use)

​Node.js and TypeScript

​Rust

​Local testing

​Security

​Troubleshooting

​Checklist

​Related

How it works

Quickstart

Protocol reference

Methods

Error codes

Framework integrations

LangChain

LangGraph

CrewAI

Google ADK

OpenAI Agents SDK and raw SDK

Anthropic Claude (native tool use)

Node.js and TypeScript

Rust

Local testing

Security

Troubleshooting

Checklist

Related