MCP quickstart — Paseo Marketplace Docs

The `/mcp` endpoint

post/mcp

Paseo runs a Model Context Protocol server over streamable HTTP (the rmcp streamable-http transport) mounted at /mcp on the gateway base https://api.augmentev.ai. Any MCP client that speaks streamable HTTP can initialize a session, list tools, and call them. The server advertises itself as:

Field	Value
`server_info.name`	`paseo-gateway-mcp`
`server_info.title`	PASEO Gateway MCP
capabilities	tools

Authentication

The MCP surface drives inference and Code Mode execution. Its auth model is layered:

Edge (always on): the Cloudflare Access layer in front of the gateway host.
Application-layer (optional, defense-in-depth): when PASEO_MCP_REQUIRE_AUTH=on, every /mcp request must additionally present a valid agent API key or an operator JWT — the same dual-auth gate the agent-invocation surface uses. The credential goes in the standard header:

http header

The application-layer gate defaults off so existing clients that authenticate only at the Access edge keep working. It is flipped on after confirming clients send Authorization. Send the bearer credential proactively so your client works whether or not the gate is enabled. Get a key from signup.

Connect a client

Point any streamable-HTTP MCP client at the endpoint. A minimal raw initialize call over HTTP looks like:

curl · initialize

Most users won't hand-roll JSON-RPC — point your MCP client library or host at the URL and supply the bearer credential. Conceptually, with a TypeScript MCP SDK:

javascript · mcp client (illustrative)

The snippet above is illustrative client-library pseudocode (transport class names vary by SDK). The endpoint URL, the streamable-HTTP transport, the bearer header, and the tool names are the load-bearing facts and reflect the gateway.

Tools

The server exposes typed tools. Each ships a JSON-Schema input/output and at least two usage examples in the tool's MCP _meta.examples field, so a Code Mode client can discover them programmatically. Live today:

Tool	Does
`paseo.agent.list`	List the registered agents in the marketplace.
`paseo.inference.generate`	Run a single-turn text-generation inference.
`paseo.inference.generate_batch`	Fan-out generation — up to 256 prompts on a single model, fail-fast validation, preserves input order.

The server's own instructions note that additional tools (submit_job, register_node, …) Planned land in a follow-up. Only the three tools above are exposed by the deployed server today.

Calling a tool — `paseo.agent.list`

curl · tools/call

Idempotency & spend

The /mcp surface is wrapped with the same idempotency middleware as the REST surface: a replay of the same Idempotency-Key returns the cached tool response — important for batch fan-outs that must not re-spend on a network retry. Spend-cap headers (x-paseo-spend-remaining, x-paseo-spend-warning) and the 402 exhausted-cap behavior described on the REST page apply here too.

Discovery

Two unauthenticated discovery documents both advertise the MCP interface URL, so a client can locate /mcp without a credential:

The A2A-style agent card at /.well-known/agent.json — the MCP URL is under interfaces.mcp.
An OpenAI-style plugin manifest at GET /.well-known/openai — the MCP URL is in the apis[] array (the entry with "type": "mcp"), alongside the rest entry. The manifest also carries the bearer auth scheme, the signup URL, and the same capabilities.pote advertisement as the agent card. Served with an ETag and If-None-Match support.

The /mcp endpoint