Add MCP server card and AI catalog for agent discovery - #2832
Conversation
Closes #2555 - static/.well-known/mcp/server-card.json points agents to the Stellar Raven MCP server (SEP-2127 v1 card schema). - static/.well-known/ai-catalog.json lists the card, the agent-skills index, the api-catalog, and llms.txt. - nginx serves the catalog as application/ai-catalog+json and sets Access-Control-Allow-Origin: * on both files. DNS-AID is out of scope. See the issue for the reasons.
There was a problem hiding this comment.
Pull request overview
Adds agent-discovery metadata for Stellar Raven and related AI resources.
Changes:
- Adds an MCP server card and AI Catalog.
- Configures MIME types and CORS headers.
- References existing agent, API, and documentation catalogs.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
static/.well-known/mcp/server-card.json |
Describes Raven’s MCP endpoint; runtime identity requires alignment. |
static/.well-known/ai-catalog.json |
Catalogs Stellar AI resources. |
nginx/nginx.conf |
Configures discovery responses; card media type and preflight handling are incomplete. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| location = /.well-known/mcp/server-card.json { | ||
| add_header 'Access-Control-Allow-Origin' '*' always; | ||
| } |
There was a problem hiding this comment.
Fixed in ece49de. The card is now served as application/mcp-server-card+json. Both files get the CORS set from discovery.md (Allow-Origin, Allow-Methods, Allow-Headers, Expose-Headers), Cache-Control public max-age=3600, and a 204 answer to OPTIONS preflight. nginx sends an ETag for static files by default.
| @@ -0,0 +1,18 @@ | |||
| { | |||
| "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json", | |||
| "name": "org.stellar/raven", | |||
There was a problem hiding this comment.
The card schema requires exactly one slash in name (pattern ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$). Raven's runtime name stellar-raven-codemode does not fit that pattern, so the card cannot copy it. version matches the runtime (0.1.0). Aligning Raven's serverInfo.name to org.stellar/raven is a follow-up in the stellar-raven repo.
- Serve the MCP Server Card as application/mcp-server-card+json. - Add the CORS headers, Cache-Control, and an OPTIONS preflight answer for both the card and the AI Catalog. - Move the shared headers into nginx/includes/agent-discovery-headers.conf.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
static/.well-known/ai-catalog.json:6
- This advertises a verifiable
did:webidentity, butdid:web:developers.stellar.orgresolves through/.well-known/did.json, and this PR/repository provides no such file; the nginx fallback will therefore return 404. Consumers that verify the catalog host will see a broken identity claim. Either publish the DID document in this PR or omit the identifier until it exists.
| { | ||
| "identifier": "urn:air:stellar.org:skills:index", | ||
| "displayName": "Stellar Agent Skills index", | ||
| "type": "application/agent-skills+json", |
There was a problem hiding this comment.
Not changed on purpose. The agent-skills discovery RFC says to serve /.well-known/agent-skills/index.json with application/json (cloudflare/agent-skills-discovery-rfc README, publishing checklist). The catalog type field names the artifact kind with the AI Catalog known type. developers.cloudflare.com does the same: catalog type application/agent-skills+json, index served as application/json.
developers.stellar.org publishes no /.well-known/did.json, so did:web:developers.stellar.org cannot be resolved. The AI Catalog host verification step resolves host.identifier as a DID and confirms the hosting domain in the DID document, which fails today. host.identifier is optional and displayName is the only required host member, so drop the claim until a DID document exists.
|
🤖 Automated message from Kaan's Automated Triage Bot. Verified against both specs. The preview serves each file with its declared media type, the four CORS headers, Decision needed: #2555 left "do we run an official Stellar MCP server?" open. This card names |
kaankacar
added
the
bot:needs-decision
Closes #2555
What
static/.well-known/mcp/server-card.json. It describes the Stellar Raven MCP server athttps://raven.stellar.org/mcpwith the SEP-2127 v1 card schema.static/.well-known/ai-catalog.json. It lists the server card, the agent-skills index, the api-catalog, and llms.txt.application/ai-catalog+json. SetAccess-Control-Allow-Origin: *on both files.Why
Agents can now find the official MCP server from the docs domain. The current SEP-2127 draft recommends the AI Catalog path. The isitagentready scanner reads
/.well-known/mcp/server-card.json. This PR covers both.DNS-AID is out of scope. The reasons are in #2555.
Verification
schema.json(ajv, JSON Schema 2020-12).serverInfo(0.1.0). The endpoint matches the Raven README.Verified on the PR preview
GET /.well-known/mcp/server-card.json: 200,application/mcp-server-card+json, the four CORS headers from the SEP-2127 discovery doc, ETag. Body matches the repo file.OPTIONSon the card: 204.GET /.well-known/ai-catalog.json: 200,application/ai-catalog+json, CORS.Cache-Controlwithno-cache. The nginxmax-age=3600value does not reach clients. This is the same for every file on the site today.