Landscape · deep-dive · /.well-known/mcp.json

agentic-first vs mcp.json.

/.well-known/mcp.json describes your MCP server - its endpoint, transport, tools, auth, capabilities, rate limits. agentic-first describes the publisher the MCP server speaks for - your jurisdiction, your registry IDs, your stage, your contact channel. They're complementary well-known files, designed to compose.

What mcp.json is

/.well-known/mcp.json is a discovery convention from the modelcontextprotocol working group - proposed in SEP-1960 and refined in SEP-2127. It lets an MCP-aware client land on a domain and find the MCP server: which transport (Streamable HTTP / stdio), which endpoint URL, which auth scheme, which tools and resources are exposed, what the rate limits and capabilities are.

It's the MCP equivalent of openapi.json - a machine-readable manifest for the protocol surface, not for the thing on the other side of it.

Side-by-side

Question	`/.well-known/mcp.json`	`/.well-known/agentic-profile.json`
Describes	The MCP server itself	The publisher the MCP speaks for (a company or person)
Layer	Protocol - transport, auth, capabilities	Identity - who, where incorporated, what stage, how to reach
Required by	MCP-aware clients (Claude Desktop, Cursor, LangChain MCP)	Directories, sourcing agents, investors, search systems
Lives at	`/.well-known/mcp.json`	`/.well-known/agentic-profile.json`
Status	Proposed (SEP-1960 / SEP-2127, modelcontextprotocol working group)	Live, v0.1.0 (defined here, served at `/schemas/`)
What's inside	`endpoint`, `transport`, `tools[]`, `auth`, `capabilities`, `rate_limits`	`profile_kind`, `tier`, `company` / `person`, `stage`, `funding`, `team`, `metrics`, `contact`
Without the other one	An agent knows how to talk to your MCP, but not who's behind it	An agent knows who you are and how to reach you, but not how to drive your MCP

How they compose on the same domain

The recommended setup for any company running a public MCP is to ship both files. They live alongside each other in /.well-known/ and answer different questions:

# /.well-known/mcp.json - "here's how to talk to my MCP"
{
  "endpoint":   "https://public-mcp.acme-robotics.example/mcp",
  "transport":  "streamable-http",
  "auth":       { "type": "none" },
  "tools": [
    { "name": "get_product_catalog", "description": "..." },
    { "name": "get_case_studies",    "description": "..." }
  ],
  "capabilities": { "session": false },
  "rate_limits": { "per_min": 60 }
}

# /.well-known/agentic-profile.json - "here's who's running it"
{
  "schema_version": "0.1.0",
  "updated_at":     "2026-04-19T00:00:00Z",
  "profile_kind":   "company",
  "tier":           "public",
  "company": {
    "name":         "Acme Robotics",
    "website":      "https://acme-robotics.example",
    "jurisdiction": "GB",
    "registry":     { "type": "companies-house", "id": "12345678",
                      "url":  "https://find-and-update.company-information.service.gov.uk/company/12345678" }
  },
  "contact": {
    "preferred_channel": "private-mcp",
    "private_mcp":       "https://private-mcp.acme-robotics.example/mcp"
  }
}

An agent doing diligence reads agentic-profile.json to confirm jurisdiction, registry, stage, and contact preference. The same agent then follows contact.private_mcp (or a public MCP pointer if that's what the publisher prefers) to drive the MCP, and reads the matching mcp.json to know which tools are available before calling them.

Why we didn't extend mcp.json instead

Tempting, but wrong. Three reasons:

Different lifecycles. Your MCP server's tools change with every release; your jurisdiction and registry IDs don't. Coupling them forces unnecessary mcp.json republishes.
Different audiences. Most readers of mcp.json are MCP clients deciding whether to call a tool. Most readers of agentic-first will never run an MCP client.
Not every adopter publishes an MCP. The lowest-bar agentic-first publisher hosts a single static JSON file - no server, no SDK. Forcing them through mcp.json would shut out the long tail.

We follow the same logic the A2A working group did with agent-card.json: separate well-known file, separate lifecycle, complementary not competitive.

The honest summary

mcp.json answers "how do I talk to your MCP". agentic-first answers "who are you and what do you want a serious reader to know". Both files belong on the same domain. Neither subsumes the other and neither blocks adopting the other; pick whichever one matches today's need and add the second when it makes sense.

Read the standard → Back to landscape