MCP Discovery & `.well-known`

TradeStaq exposes a standards-compliant discovery surface so AI agents and MCP clients can find, authenticate, and interact with the platform programmatically. No human-in-the-loop required for the first contact.

This page is the map. If you're building an MCP client, a trading-agent framework, or anything that wants to consume TradeStaq programmatically, start here.

The Discovery Endpoints

All served from https://www.tradestaq.com:

Endpoint	Spec	What it tells you
`/.well-known/mcp/server-card.json`	SEP-1649	MCP server card: hosted streamable-http endpoint + stdio npm package
`/.well-known/api-catalog`	RFC 9727	`application/linkset+json` catalog linking REST API + MCP to docs, health, metadata
`/.well-known/oauth-authorization-server`	RFC 8414	OAuth 2.1 AS metadata: issuer, endpoints, grant types, PKCE, auth methods
`/.well-known/oauth-protected-resource`	RFC 9728	Advertises the API resource and its authorization server. Also carries `mcp_resource` for strict MCP 2025-06-18 clients
`/.well-known/agent-skills/index.json`	Agent Skills RFC v0.2.0	Catalog of installable AI-agent workflow skills with sha256 digests

Plus two content-negotiation surfaces:

Surface	What it does
RFC 8288 `Link` response headers on `/` and `/docs/*`	Point to the catalog, server card, API docs, MCP docs
`Accept: text/markdown` on `/` and `/docs/*`	Returns clean markdown (llms.txt-style) instead of the HTML React app

Typical First-Contact Flow

A programmatic client's happy path:

1. GET https://www.tradestaq.com/.well-known/mcp/server-card.json
   → Learns: streamable-http at https://mcp.tradestaq.com/mcp
            stdio via `npx @the-staq/tradestaq-mcp`

2. GET https://www.tradestaq.com/.well-known/oauth-authorization-server
   → Learns: where to register, authorize, exchange tokens; PKCE mandatory

3. POST https://www.tradestaq.com/api/oauth/register
   → Self-registers, gets client_id

4. Redirects user through /api/oauth/authorize → /oauth/consent → redirect_uri
   → Gets single-use authorization code

5. POST https://www.tradestaq.com/api/oauth/token
   → Exchanges code for a 60-min access JWT + a rotating 30-day refresh token (scope=mcp)

6. Connects to https://mcp.tradestaq.com/mcp with Authorization: Bearer <jwt>
   → Consumes tools, prompts, resources

See MCP Authentication for full OAuth 2.1 + DCR details.

MCP Server Card (SEP-1649)

GET /.well-known/mcp/server-card.json returns the canonical MCP server descriptor. Includes:

name, vendor, version — human-readable identity
transports — both http-streamable (URL) and stdio (package name + args)
auth — pointer to the OAuth Authorization Server metadata
capabilities — whether the server offers tools, prompts, resources

A third-party client that finds your site can discover everything needed to connect in one request.

API Catalog (RFC 9727)

GET /.well-known/api-catalog returns application/linkset+json with links covering:

REST API (/api) + its OpenAPI docs
MCP endpoint (mcp.tradestaq.com/mcp) + its docs
Health endpoints (/health, mcp.tradestaq.com/health)
OAuth metadata files

Use this when a client wants a single authoritative index of every TradeStaq surface.

Agent Skills Index

GET /.well-known/agent-skills/index.json lists installable AI-agent workflow skills. Each entry has a sha256 digest computed dynamically from the skill file's content so the digest cannot drift from the source.

Current skills:

deploy-tradestaq-bot — tells an agent how to deploy a TradeStaq bot safely
backtest-strategy — walks an agent through running a backtest
forge-strategy — guides an agent through AI-generated strategy creation

Each skill is a ~50-line workflow guide at /.well-known/agent-skills/<name>/SKILL.md. Agents download the skill, verify the digest, and execute the workflow using MCP tools.

Markdown Content Negotiation

Send Accept: text/markdown (at or above HTML in the q-value list) to:

https://www.tradestaq.com/ — returns src/content/agent-home.md, a clean llms.txt-style overview of TradeStaq
https://www.tradestaq.com/docs/* — returns the MDX source with imports/exports/JSX stripped

Browsers, which list HTML at high q-value, still get the React app. This means AI scanners and crawlers (ChatGPT, Claude, Perplexity, isitagentready.com) get clean markdown without any user agent sniffing.

WebMCP (In-Browser)

The homepage mounts a client component that registers three zero-auth tools via navigator.modelContext when the browser supports WebMCP:

getProductInfo
getSupportedExchanges
getMcpServerInfo

A WebMCP-enabled browser (e.g., WebMCP-Chrome) discovers these automatically — no OAuth, no keys. Good for answering "what is TradeStaq" and "how do I connect" without any authentication.

RFC 8288 Link Headers

The homepage and /docs/* emit Link response headers pointing to:

The API catalog (rel="service-catalog")
The MCP server card (rel="mcp-server-card")
API docs (rel="api-docs")
MCP docs (rel="mcp-docs")

A crawler that reads the headers learns where to go without parsing HTML.

Next Steps

MCP Authentication — Full OAuth 2.1 + DCR flow
MCP Server Overview — Capabilities, tools, prompts, resources
HTTP Transport — Connecting to mcp.tradestaq.com/mcp
Setup Guide — End-user AI client configuration

MCP Discovery & .well-known