All chapters
  1. Start hereA protocol standardizes the call. It does not grant the permission
  2. Foundations · 1The primitive: a function, its arguments, its result, its side effects
  3. Foundations · 2Function calling: the model asks, your application executes
  4. Foundations · 3Client and server: process boundaries, JSON-RPC, errors and trust
  5. Foundations · 4What MCP is: host, client, server and what the protocol promises
  6. Protocol · 5Three surfaces: tools act, resources inform, prompts guide
  7. Protocol · 6A first MCP server: typed input, deterministic data, the raw exchange
  8. Protocol · 7Java and the SDKs: typed DTOs, validation and interoperability
  9. Protocol · 8Local or remote: stdio, HTTP, stateless requests and availability
  10. Platform · 9The database decision: direct SQL, a service boundary or an MCP adapter
  11. Platform · 10Sharing across teams: ownership, catalogs, contracts and versions
  12. Platform · 11Who gets access: users, agents, delegation and least privilege
  13. Platform · 12Enterprise authorization: tokens, audiences, gateways and no passthrough
  14. Platform · 13The threat model: injection, poisoned tools, confused deputies and egress
  15. Platform · 14Governance: who may publish, who approves, who answers the page
  16. Operations · 15Observability and audit: what was called, by whom, and why it was allowed
  17. Operations · 16Resilience: timeouts, retries, idempotency and overload at a shared server
  18. Operations · 17Testing and evaluation: contracts, authorization matrices and injection
  19. Reference · 18Advanced MCP: long tasks, large catalogs, tenants and evolving versions
  20. Reference · 19The ecosystem: SDKs, registries, gateways, identity and telemetry
  21. Reference · 20Enterprise reference architecture: one assessment platform, four teams
  22. Reference · 21Decision playbooks: function, API or MCP, and the records that explain why
  23. ReferenceGlossary
  24. AboutAbout this site and its sources
Platform · 10

Sharing across teams: ownership, catalogs, contracts and versions

When four teams depend on one capability, the hard problems are ownership, names, versioned schemas and meaning that stays stable. Catalogs, registries and the publishing workflow.

You will understand
Why one capability shared by four teams needs two kinds of owner: the platform and the domain.
You will be able to tell apart
Your organization's tool catalog and the public MCP Registry, and what each one can and cannot promise.
You will know
Why a field that keeps its name but changes its meaning is worse than a breaking change, and how to version so it never happens.

On a Monday in September, the property-risk data team shipped version 2 of get_roof_assessment. Version 1 had looked a roof up by property_id. That turned out to be ambiguous, because one property can carry several submissions over the years, so version 2 takes submission_id instead. The team announced the change in its own channel and moved on.

By ten o'clock the claims team's assistant was failing on every storm claim. Its client had been built against version 1 and still sent property_id. The server answered each call with an error: invalid arguments, a required submission_id missing, an unknown property_id present, and a note that version 1 was deprecated with the name of its replacement. The claims developer read the error, changed one argument, and redeployed before lunch. This is this site's own case UW-M07.

That was a good failure. It was loud, it named the fix, and it hurt one morning. In the same planning meeting someone had proposed a cheaper change: keep the old argument name and quietly return the newest submission's roof for a property. No client would have broken. Every client would have started receiving a different roof for some properties, with no error, and the claims team would have found out months later from a disputed claim.

With four teams on one capability, the hard problems are no longer in the code: who owns which part, how a team finds the capability and knows it is approved, what a version promises, and how meaning stays stable while code changes.

One capability, four teams#

The MCP server uw-assessment wraps the assessment service (The database decision, option 3). Four teams consume it. Each team runs its own host application, has its own client id, its own token with its own scopes, its own rate limit and its own metrics.

Claims reads roof facts for storm claims. Underwriting has two clients: the agent workbench, which recommends, and the cockpit, through which a person decides. Support sees only a status summary; analytics sees only aggregates. The lab runs a scripted workload per team against the example's real HTTP server and shows each team's visible tools, a sample call and its isolated metrics.

The numbers are synthetic counts from a scripted workload; they measure nothing.

TeamClientScopesVisible toolsCalls / allowed / refused / rate limitedBucket
claimsclaims-assistantuw.readget_roof_assessment, search_guidance, check_eligibility6 / 4 / 1 / 13, refill 1 per s
underwritinguw-workbenchuw.read uw.recommendthe three reads and record_recommendation4 / 4 / 0 / 010, refill 5 per s
underwritinguw-cockpit (the underwriter)uw.read uw.decidethe three reads and record_underwriter_decision1 / 1 / 0 / 05, refill 1 per s
supportsupport-desksupport.readget_assessment_status3 / 2 / 1 / 05, refill 2 per s
analyticsanalytics-jobsanalytics.readget_assessment_stats4 / 2 / 1 / 12, refill 1 per s

Run in a scratch copy on 2026-11-18, teams.py prints the same counts:

/opt/homebrew/bin/python3 teams.py
claims        claims-assistant  uw.read                {"calls": 6, "allowed": 4, "refused": 1, "rate_limited": 1, "errors": 0}
underwriting  uw-workbench      uw.read uw.recommend   {"calls": 4, "allowed": 4, "refused": 0, "rate_limited": 0, "errors": 0}
underwriting  uw-cockpit        uw.read uw.decide      {"calls": 1, "allowed": 1, "refused": 0, "rate_limited": 0, "errors": 0}
support       support-desk      support.read           {"calls": 3, "allowed": 2, "refused": 1, "rate_limited": 0, "errors": 0}
analytics     analytics-jobs    analytics.read         {"calls": 4, "allowed": 2, "refused": 1, "rate_limited": 1, "errors": 0}
totals {"calls": 18, "allowed": 13, "refused": 3, "rate_limited": 2, "errors": 0}

The claims assistant's fourth call within 300 ms found its bucket empty, and no other team was slowed. Its call for SUB-2001, a commercial-east submission, answered not_found, exactly like a missing one (case UW-M11). Support and analytics, calling get_roof_assessment, got 403 insufficient_scope (case UW-M12). A rate limit, a tenant check and a scope check all need to know which team is calling; separate identities make each of them possible.

Before AI. A backend engineer has seen this as a shared internal API or a shared library. A shared library couples every consumer to every release. A shared API with one consumer key for everyone makes every incident impossible to scope. The working pattern was always one service, one contract, and one credential per consuming application. MCP inherits the pattern unchanged.

Two kinds of ownership#

Ask "who owns get_roof_assessment?" and the honest answer is several people, each for a different part. Confusing the parts is how capabilities rot: the team that runs the server is paged for a wrong roof age, or the team that owns the data learns about a new consumer from an audit.

A platform team is the team that runs the shared infrastructure through which capabilities are offered: the gateway, the catalog, identity integration, shared dashboards. It owns how capabilities are reached, not what they mean. For example, the platform team adds get_roof_assessment version 2 to the catalog and the gateway policy; it cannot tell you whether 22 years is the right roof age for PROP-2207.

The assessment domain owns what the capability means; the table names the other owners.

Part of the capabilityOwnerExample decision
Data, rules, database schemaassessment domain (property-risk data team)R-ROOF-03 escalates when the gap exceeds 5 years
Tool names, schemas, versionsuw-assessment server maintainersversion 2 takes submission_id
Catalog entry, gateway policy, shared metricsplatform teamversion 2 is discoverable; version 1 is deprecated
Scopes and which principals may hold themidentity and security governanceno agent may hold uw.decide usefully
A consumer's client, token and use of resultseach consumer application ownerclaims shows the roof age to an adjuster

The full RACI of these six roles, with the escalation path, lives on Governance. What matters here is the split itself. This site's recommendation: the platform team owns reach, the domain owns meaning, and every catalog entry names both.

The catalog: what the organization knows about a tool#

An MCP tools/list entry describes a tool to a model. Normative (MCP specification 2026-07-28): a Tool has a required name and inputSchema, and optional title, description, icons, outputSchema, annotations and _meta (schema). Nothing in that list says who owns the tool, what version it is, which data it returns or how risky it is. The protocol does not need to know. The organization does.

A tool catalog is the organization's list of approved capabilities, one record per tool version, with the facts a protocol entry does not carry: owner team, maintainer, version, required scopes, principal types, data class, risk tier and lifecycle state. For example, the catalog record of record_underwriter_decision says: version 1, write, scope uw.decide, principal type user, role underwriter, client uw-cockpit, risk tier critical, owner property-risk-data, state monitored.

In the example the catalog is catalog.py, and the MCP entry is generated from it (mcp_definition keeps only the fields MCP defines). The platform team's view, from catalog_rows(), run in a scratch copy on 2026-11-18:

get_roof_assessment          v1 read  uw.read         medium   property-risk-data     deprecated
get_roof_assessment          v2 read  uw.read         medium   property-risk-data     monitored
search_guidance              v1 read  uw.read         low      underwriting-standards monitored
check_eligibility            v1 read  uw.read         medium   property-risk-data     monitored
get_assessment_status        v1 read  support.read    low      property-risk-data     monitored
get_assessment_stats         v1 read  analytics.read  low      property-risk-data     monitored
record_recommendation        v1 write uw.recommend    high     property-risk-data     monitored
record_underwriter_decision  v1 write uw.decide       critical property-risk-data     monitored

The first row is a deprecated version, no longer listed to callers but remembered so the server can explain UW-M07. The third row has another owner, underwriting-standards: one server can carry tools of several domains, and the catalog shows it.

Common confusion. "The tool list is our catalog." It is not. The tool list is what one caller is shown at one moment, filtered by its permissions; the example marks it cacheScope private for that reason. The catalog is the complete, owned record behind every list, including tools a caller will never see.

The public MCP Registry, and why it is not your catalog#

Teams that hear "catalog" often reach for the MCP Registry. They are different things with different jobs, and mixing them up leads to either publishing private servers or trusting public ones too much.

The MCP Registry is, in its own documentation, "the official centralized metadata repository for publicly accessible MCP servers". It stores metadata that points to packages (on npm, PyPI, Docker Hub and others) or to public remote URLs; it does not host code. Everything in this section is an ecosystem pattern, described from the registry's documentation as read on 2026-11-18, and not part of the MCP specification.

What the documentation says, briefly:

TopicAs documented on 2026-11-18
Status"currently in preview"; breaking changes or data resets may occur before general availability
What is storeda server.json per server version: unique name, where to find it, how to run it, discovery data
Private serversnot supported; for those, "host your own private MCP registry"
Who consumes itprimarily downstream aggregators such as marketplaces, not host applications directly
Trustnamespace authentication; security scanning is left to package registries and aggregators
Remote URLsthe registry verifies the namespace in name; it does not verify that you control the remote URL

A namespace is a prefix that ties a name to an owner who has proven control of it. In the registry, names are reverse DNS: io.github.username/server for a verified GitHub account, or a domain's reversed name such as com.example/server, proven by a DNS TXT record on the domain or by a file served at /.well-known/mcp-registry-auth.

Here is what a server.json for uw-assessment would look like, written from the remote-only example in the registry's quickstart. It is documented shape; not validated and not published. The public registry would refuse it anyway, because the server is reachable only inside the insurer:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "example.insurer/uw-assessment",
  "title": "Underwriting assessment",
  "description": "Roof assessments, eligibility checks and recommendations for commercial property submissions.",
  "version": "2.0.0",
  "remotes": [
    {"type": "streamable-http", "url": "https://mcp.uw.insurer.example/mcp"}
  ]
}

Read it against the catalog rows above. The registry format says where the server is and how to reach it; it says nothing about who owns each tool, which scopes it needs or what risk tier it carries. That is by design: the registry is deliberately unopinionated so that aggregators can add curation. The insurer needs its own catalog regardless. This site's recommendation: keep the organization's catalog as the source of truth for ownership, scopes, risk and lifecycle; if hosts in the organization expect registry-style discovery, run a private registry that implements the registry's OpenAPI interface and generate its entries from the catalog, never the other way round. Treat any public server found through an aggregator as a third-party dependency that needs the Threat model and a catalog entry of its own before a host connects to it.

Names and namespaces#

A name is the one part of a contract every consumer hard-codes. It must be stable, unique where it is resolved, and owned.

Normative (MCP specification 2026-07-28): tool names should be 1 to 128 characters, case-sensitive, using only A-Z, a-z, 0-9, underscore, hyphen and dot, and unique within one server. A client that aggregates several servers should disambiguate colliding names, for example by prefixing a server identifier, and should not rely on the server's own name for that (tools).

That rule is about one server. If the claims host connects uw-assessment and a weather server that both offer get_assessment, the protocol leaves the collision to the host; the organization's catalog is where it is prevented.

This site's recommendation: name servers by domain (uw-assessment, never team-a-tools), name tools as a verb and a business noun (get_roof_assessment, record_recommendation), never put a version number or a team name in a tool name, and let the catalog reject a new tool whose name or meaning duplicates an existing one. Use reverse DNS of a domain the organization controls (example.insurer/uw-assessment) as the server's catalog key, so that a private registry and the public one can never be confused.

Service contracts#

A service contract is everything a consumer may rely on about a capability, written down and owned: inputs, outputs, errors, the meaning of each field, who may call it, its limits and how it will change. For example, the contract of get_roof_assessment version 2 says: argument submission_id matching ^SUB-[0-9]{4}$; result a PropertyAssessment with nine fields; roof_age_years is the provider's assessed age in whole years; errors invalid_arguments, not_found, not_authorized, timeout, rate_limited; scope uw.read; deprecation with at least one named replacement and a date.

The MCP tool definition carries the machine-checkable part of that contract. Normative (MCP specification 2026-07-28): if a tool declares an outputSchema, the server must return structured results that conform to it, and clients should validate them. The example's get_roof_assessment declares the DTO's JSON Schema as its output schema, and its execution errors carry no structured content, so an error can never break that schema.

The rest of the contract has no field in the protocol. "Whole years, as assessed by the provider" is not a JSON Schema keyword. Neither is "deprecated versions stay callable until the announced date". That text lives in the description, in the catalog and in the documentation the domain team owns. This site's recommendation: write the meaning of every field next to its schema, in the catalog, and treat a change to that text as a contract change.

Before AI. This is an OpenAPI document with a sentence of meaning under each field and a deprecation policy on top. MCP adds a new kind of consumer: a model that reads the description to decide whether to call the tool, which makes the prose part of the contract matter more.

Versioned schemas: the case of the version-1 client#

Semantic versioning is a convention for version numbers in three parts, MAJOR.MINOR.PATCH, where each part promises something about compatibility. As written in Semantic Versioning 2.0.0 (read on 2026-11-18): increment MAJOR for incompatible API changes, MINOR for backward-compatible functionality, PATCH for backward-compatible bug fixes; and once a version is released, its contents must not be modified. For example, adding an optional output field is a MINOR change; replacing a required argument is a MAJOR one.

MCP itself is versioned differently, and the two must not be confused. The protocol revision is a date (2026-07-28) that marks the last backward-incompatible change to the protocol. A tool's version is the organization's business: normative (MCP specification 2026-07-28): the Tool definition has no version field. The protocol neither requires nor forbids tool versions; it leaves them to whoever owns the tool.

The example keeps one tool name and versions it in the catalog. Version 1 took property_id; version 2 takes submission_id. Only version 2 is listed. When a request fails validation against version 2, the server checks whether it would have passed version 1 and, if so, says so. A script in a scratch copy of the example calls version 2 with version-1 arguments (the server and the call helper are the example's own; the script is this page's):

"""Scratch demo for the sharing page: UW-M07 (a version-1 client calls version 2)."""
import json

from clock import SimClock
from mcp_server import McpServer, local_claims
from scenarios import core_call

clock = SimClock()
server = McpServer(clock=clock, transport="stdio")
ctx = {"claims": local_claims("underwriting-agent", clock), "token": None, "transport": "stdio"}
v1 = core_call(server, ctx, "get_roof_assessment", {"property_id": "PROP-2207"})
print(json.dumps(v1["error"], indent=1))
v2 = core_call(server, ctx, "get_roof_assessment", {"submission_id": "SUB-1004"}, 2)
print("v2 call ok:", v2["ok"])
server.service.close()
{
 "code": "invalid_arguments",
 "message": "The arguments do not match the input schema of get_roof_assessment version 2.",
 "retryable": false,
 "violations": [
  {
   "path": "/submission_id",
   "keyword": "required",
   "message": "missing required property submission_id"
  },
  {
   "path": "/property_id",
   "keyword": "additionalProperties",
   "message": "unknown property property_id"
  }
 ],
 "deprecated_version": {
  "version": 1,
  "note": "v1 took property_id; one property can carry several submissions, so v2 takes submission_id. Deprecated 2026-09-01; retirement planned 2027-01-31 (synthetic dates).",
  "replaced_by": "get_roof_assessment v2 (argument submission_id)"
 }
}
v2 call ok: True

retryable false says a resend will not help. The violations name exact paths, so the fix is visible without the server's code. deprecated_version turns "you are wrong" into "you are one version behind, and here is why". It is a tool error (isError true) that the model and the developer both see. The case runs as the underwriting agent; the claims assistant, with the same uw.read, gets the same answer, because validation runs before authorization.

Diagram: UW-M07 · a version-1 client meets version 2, and the error explains itself

Time runs down the page. The client still sends property_id. The server validates against version 2, sees two violations, checks whether the request would have fit version 1, and says so. The developer changes one argument and the next call succeeds. A loud break with a named fix is the good kind of failure.

  1. Client built for v1 to MCP server uw-assessment: tools/call get_roof_assessment property_id PROP-2207. A request shaped for version 1.
  2. MCP server uw-assessment: validate against v2: /submission_id required, /property_id unknown. Two violations with exact paths, before any authorization or execution.
  3. MCP server uw-assessment to Catalog: would v1 accept these arguments?. The server looks for an older version whose schema fits.
  4. Catalog to MCP server uw-assessment: yes: v1, deprecated 2026-09-01, replaced by v2. Synthetic dates; retirement planned 2027-01-31.
  5. MCP server uw-assessment to Client built for v1: isError invalid_arguments + deprecated_version. A tool error the model and the developer can both read; retryable false.
  6. Consumer developer to Client built for v1: send submission_id instead. One change in the consumer's code.
  7. Client built for v1 to MCP server uw-assessment: tools/call get_roof_assessment submission_id SUB-1004. The version-2 call succeeds and returns the PropertyAssessment.

Version 2 breaks version-1 clients. That was deliberate and correct: the old argument was ambiguous, and a loud break is the honest way to fix an ambiguous contract. The ev-sharing-versioning block below compares this choice with a new tool name or a new server.

Semantic compatibility: same name, new meaning#

Now the change that was proposed and rejected in the opening. It is worth walking through, because it is the one no schema check can catch. The scenario below is hypothetical and not in the example's code.

Suppose the property-risk data team decides that roof_age_years should mean "years since the last full replacement" instead of "years since the roof was installed, as the provider assessed it". The field keeps its name, its type (an integer from 0 to 150) and its place in the DTO. Every schema check passes. Every client keeps working.

Follow SUB-1004. The application said the roof is 9 years old; the provider said 22 (evidence EV-ROOF-0412). R-ROOF-03 sees a 13-year gap and the outcome is escalate, which is series case UW-004. If the provider's records show a partial repair 8 years ago that the new definition counts as a replacement, the field now says 8. The gap is 1 year. check_eligibility answers eligible. The underwriting agent recommends approval with a citation that looks correct. The claims assistant shows an adjuster a younger roof. Analytics reports that old roofs became rare overnight. Nothing failed, so nobody looks.

Semantic compatibility is the property that every field, value and error keeps the meaning consumers rely on, not only its name and type. A semantic break is worse than a breaking change because it is silent (no error, no failing test unless a test checks values), spread out (each consumer goes wrong in its own way, far from the cause) and hard to undo (recommendations and reports built on the new meaning are already stored).

Diagram: Same name, new meaning · a hypothetical change that every schema check passes

Read left to right, top row then bottom row. Both rows have the same field name, type and range. Only the meaning of roof_age_years differs, and with it the gap that rule R-ROOF-03 sees. The top row escalates SUB-1004 to a person; the bottom row calls it eligible. No error appears anywhere. The bottom row is hypothetical, not in the example's code.

  1. The field
    1. roof_age_years = 22: The contract as written today. Evidence EV-ROOF-0412.
    2. roof_age_years = 8: Hypothetical. Same name, same type, same range. A partial repair now counts as a replacement.
  2. Rule R-ROOF-03
    1. gap 13 years: Application 9, provider 22: the rule escalates.
    2. gap 1 year: Application 9, field 8: the rule sees nothing wrong.
  3. What consumers see
    1. escalate: The underwriter sees the conflict and decides.
    2. eligible: Every consumer draws a wrong conclusion its own way: underwriting, claims and analytics alike.

The defenses are ordinary and must be deliberate. A new meaning gets a new name: roof_years_since_replacement beside roof_age_years, a MINOR change that breaks nobody. The meaning of every field is written in the contract, so a change to it is visible in review. Contract tests check values, not only shapes: "for SUB-1004, roof_age_years is 22 and check_eligibility is escalate". The example's golden cases do exactly this for every case id (Testing). This site's recommendation: treat any change to what a field means as a MAJOR change, even when the schema is identical, and route it through the domain data owner's review.

Publishing, in brief#

A tool another team can discover is a product with users. In the example it moves through eight states, draft to retired, and each move needs one role; a wrong role is refused. The full lifecycle, the RACI and the escalation path are on Governance. Run in a scratch copy, the lifecycle function refuses a maintainer who tries to approve:

{'ok': False, 'new_state': 'reviewed', 'reason': 'wrong_role: approve needs security-governance, not server-maintainer'}
{'ok': True, 'new_state': 'approved', 'reason': 'Security approves the scopes, the principal types and the risk tier.'}

The lab below opens on a monitored tool. Try deprecating it as the platform team, then as the domain data owner.

ActionFrom → toRoleWhy
reviewdraft → revieweddomain-data-ownerthe data owner confirms what the tool means and which data it exposes
rejectreviewed → draftsecurity-governancea scope, a risk tier or a data class is wrong
approvereviewed → approvedsecurity-governancesecurity approves scopes, principal types and risk tier
versionapproved → versionedserver-maintainerthe schema is frozen as a version and shipped in the server
publishversioned → discoverableplatform-teamadded to the catalog and the gateway policy
monitordiscoverable → monitoredplatform-teamdashboards, alerts and an on-call owner are in place
deprecatemonitored → deprecateddomain-data-ownerthe replacement and a retirement date are named
retiredeprecated → retiredplatform-teamno consumer calls it; it leaves the catalog and the server

A tool is listed in tools/list only when discoverable or monitored, still callable when deprecated, and unknown when retired. That is why UW-M07 could explain itself: version 1 was deprecated, not retired.

Diagram: One capability, four teams, two kinds of owner · the platform owns reach, the domain owns meaning

Read left to right. Four teams' clients each carry their own token, rate limit and metrics. The platform team runs the catalog and the gateway policy, which decide who reaches what. The server maintainers own the tool schemas and versions. The assessment domain owns the data, the rules and the schema behind them. Click a box for the owner and an example decision.

  1. Consumers · one client id each
    1. claims-assistant: The claims team's agent. Reads roof facts for storm claims; its own bucket of 3, refill 1 per second.
    2. uw-workbench + uw-cockpit: The underwriting team: the agent recommends through the workbench; a person decides through the cockpit.
    3. support-desk: Sees one summary tool, get_assessment_status. No roof facts.
    4. analytics-jobs: Sees aggregates only, get_assessment_stats.
  2. Platform team · reach
    1. Tool catalog: The organization's record of every tool version. The tool list each caller sees is generated from it.
    2. Gateway policy + per-team metrics: Routes calls, enforces organization-wide policy and keeps each team's metrics apart.
  3. Server maintainers · contract
    1. MCP server uw-assessment: Validates arguments against the current version, authorizes every call, calls the service.
  4. Assessment domain · meaning
    1. Assessment service: Owns R-ROOF-03 and the meaning of every DTO field. The domain data owner is the property-risk data team.
    2. Database schema: Private to the domain; consumers depend on the DTO and the tool schemas, never on tables.

What goes wrong without these ideas#

Missing ideaWhat happens
One client id per teamA rate limit, a tenant check or an incident cannot tell claims from analytics; one team's burst slows everyone
Two kinds of ownerThe platform team is paged for a wrong roof age; the domain learns about a new consumer from an audit
A catalog behind the tool listNobody can answer which tools exist, who owns them, or which were deprecated
Versioned schemas with deprecationVersion 2 replaces version 1 in place; old clients get "unknown property" with no explanation
Semantic compatibilityA field changes meaning; every consumer is wrong and nothing fails

Security and governance notes#

Security note. Sharing multiplies the cost of a mistaken grant. Give each consumer its own client id and token, filter the list per caller and check every call (case UW-M03 shows why the call check is the one that counts), and never trust a server because it is in a registry: the registry verifies namespaces, not code, not even control of a remote URL.
Governance note. The catalog entry is the place where ownership becomes checkable: an owner team, a maintainer, an approved scope, a risk tier and a state on every tool, and the ADR that granted each team its access one click away (Playbooks). A tool without an owner in the catalog is not shared; it is abandoned in public.
In a coding agent. A company that gives its developers' coding agents shared MCP servers meets the same questions. A repository server and an issue tracker server need catalog entries with owners. A field such as draft on open_pull_request must not quietly change from "not ready for review" to "do not run CI", or every agent's pull requests change behavior at once. And a public server found in a marketplace is a dependency that a security team reviews before any agent connects to it. Diff to Deploy shows the review path such a pull request takes.
What this is not. This page covers the contract between a shared capability and its consumers. Typed data contracts in depth (schema design, validation, repair) belong to https://schema.sammuthu.com, and the full publishing lifecycle with its RACI belongs to Governance.

Checklist for Monday#

CheckPass when
Identity per teamEvery consuming application has its own client id, token, rate limit and metrics
OwnersEvery catalog entry names the domain owner, the maintainer and the platform contact
Catalog versus listThe catalog holds every version and state; the tool list is generated from it per caller
NamesServer and tool names follow one convention; no version or team name inside a tool name
ContractEvery field has a written meaning; output schemas are declared and conform
VersionsIncompatible changes get a new version; the old one stays callable and explains itself until its date
MeaningA change in what a field means is reviewed as a major change; contract tests check values
Public serversAnything from a registry or marketplace gets a catalog entry and a threat review first

Exercises#

  1. The support team asks for get_roof_assessment because brokers ask about roof ages. Which parts of this page apply, and what do you offer first?
  2. The property-risk team wants assessed_at to mean "when our service fetched the record" instead of "when the provider assessed the roof". Is that a MINOR or a MAJOR change, and how do you ship it?
  3. A developer proposes listing uw-assessment in the public MCP Registry "so other hosts can find it". What do you answer?
AnswersOne line each
  1. A scope request (owners, ADR-005-style review); first offer get_assessment_status or a new narrow tool, since support holds support.read and get_roof_assessment returns evidence ids.
  2. MAJOR in meaning even though the schema is unchanged; add a new field such as fetched_at, keep assessed_at's meaning, and deprecate nothing that consumers rely on.
  3. The public registry does not accept private servers; publish it in the organization's catalog, and in a private registry generated from that catalog if hosts need registry-style discovery.
One server per domain, per team, or behind one gateway?Three ways to lay out shared servers, and what each does to ownership

One server per domain is the example's shape: uw-assessment carries the assessment domain's tools for every team. Ownership is clear, the domain's rules stay in one service, and the catalog has one entry per tool. The cost is that every team's traffic meets in one place, so per-client rate limits and metrics are not optional; the shared lab shows the claims burst contained to claims.

One server per consuming team looks tidy ("the claims server", "the analytics server") and is almost always a mistake. Each team's server ends up wrapping the same service with slightly different tools, the same rule gets re-implemented in four adapters, and a change in the domain needs four releases. If teams need different views, give them different tools on the domain's server, with different scopes, as the example does with get_assessment_status and get_assessment_stats.

An aggregating gateway in front of many domain servers is the usual answer at scale: hosts connect to one endpoint, and the gateway routes each call to the owning server, applies organization-wide policy and records audit events. Whether to build or buy one is a question for Ecosystem; here only the design rules matter. Two things to keep: the gateway must not become the place where domain rules live, and name collisions across servers must be solved in the catalog before the gateway has to rename anything, as the specification's disambiguation rule asks of aggregating clients.

Running a private registry next to the catalogWhat the public registry's design suggests for an internal one, and where it stops

The registry documentation read on 2026-11-18 describes a layered design: the public registry holds minimal, unopinionated metadata; aggregators and subregistries pull it on a regular, infrequent schedule (the documentation's example is once per hour) and add their own data; hosts consume the aggregators through the registry's OpenAPI interface. A subregistry may add custom data under _meta with its own key, and the documentation's example key is com.example.subregistry/custom.

An organization can copy the shape without the code. The documentation says the official codebase is not designed for self-hosting, so an internal registry is a separate implementation of the same OpenAPI interface. Its entries are generated from the catalog: name, remote URL and description from the catalog's server record; owner, risk tier and approved scopes under the organization's own _meta key. Hosts that understand the interface can then discover internal servers the same way they would discover public ones.

Three limits matter. The registry format describes servers, not individual tools, so per-tool ownership and scopes stay in the catalog. Registry metadata is immutable except its status, which suits an audit trail but means a correction is a new version. And discovery is not authorization: a host that finds uw-assessment in the internal registry still needs a token with the right audience and scopes before any call succeeds (Enterprise authorization).

Three ways to version a tool, comparedSame name with a catalog version, a new tool name, or a new server; each moves the cost somewhere else

Same name, version in the catalog (the example's choice). Consumers keep the name they know; the server lists only the current version and recognizes requests shaped for the deprecated one, as UW-M07 shows. The cost is that a client cannot pick a version: the day version 2 ships, every version-1 client breaks, loudly. That is acceptable when the old contract was wrong, as property_id was, and when the deprecation was announced to every consumer application owner found in the audit events.

A new tool name (get_roof_assessment_by_submission beside the old tool). Both versions are listed at once and clients migrate at their own pace. The cost is in the model's context and in the catalog: two near-identical tools in one list can confuse the model about which to call, and the old one must still be retired on a date. It suits additive changes that some consumers do not need yet.

A new server or endpoint per major version. Hosts connect to the old or the new server explicitly, and the platform team runs both during the migration. This is the heaviest option and suits a change of the whole contract, such as a new domain model. This site's recommendation: default to the first, use the second when two versions must coexist for longer than one release of the slowest consumer, and reserve the third for a contract that changes as a whole. In every case, put the version and its state in the catalog, keep the old version callable and self-explaining until its retirement date, and watch per-version call counts fall to zero before retiring it.

Lists that differ by caller, and catalogs that driftWhy a shared list must never be cached across teams, and how a host learns that tools changed

Each team sees a different tool list from the same server (case UW-M02 for the series principals; the table above for the four teams). That makes caching subtle. Normative (MCP specification 2026-07-28): list results carry ttlMs and cacheScope; a private result must not be shared across authorization contexts, so a different access token needs a different cache entry. The example marks its tool list private because it depends on who asks. A gateway that cached one list for everyone would show the analytics team the claims team's tools, or the reverse.

Lists also change over time: a tool is published, deprecated or retired. The specification lets a server tell listening clients that its tool list changed, through subscriptions/listen with toolsListChanged and the notifications/tools/list_changed notification; the example's server declares listChanged false and relies on the time to live. A host that never refreshes keeps offering its model a retired tool until a call fails.

The deeper risk is a list that changes in meaning without changing in name: a description edited to say something new, an annotation flipped. That is the semantic-compatibility problem applied to the catalog itself, and on a dynamic catalog it can be an attack (Advanced MCP and the Threat model cover rug pulls). This site's recommendation: version descriptions with the schema, and have the platform team diff each published list against the catalog on every release.

In one breath#

When four teams share one capability, give each its own client id, token, rate limit and metrics, and split ownership: the platform team owns how the capability is reached, the domain owns what it means. Keep an organization catalog with an owner, version, scopes, risk tier and state for every tool; the public MCP Registry is a preview-stage index of public servers, not a substitute. Version every incompatible change and keep the old version explaining itself until its date, and treat any change in what a field means as a major change, because a silent change in meaning is worse than a loud break.

The catalog now says which team may use which tool, and the server refuses everyone else. But "the claims team" is not one caller. It is a person at a desk, an agent acting for that person, and a batch job acting for nobody in particular, and each needs a different kind of identity and a different kind of permission. That is Who gets access.