Agents

Your agent should not guess attribute names

A model's training data is months behind the registry, and the conventions rename keys most releases. This site is also a read-only MCP server at https://semconv.com/mcp. No key, no account, one URL. Add it once and your agent checks the registry instead of its memory.

Add it to your client

claude mcp add --transport http semconv https://semconv.com/mcp

codex mcp add semconv --url https://semconv.com/mcp

.cursor/mcp.json

{
  "mcpServers": {
    "semconv": { "url": "https://semconv.com/mcp" }
  }
}

.vscode/mcp.json

{
  "servers": {
    "semconv": { "type": "http", "url": "https://semconv.com/mcp" }
  }
}

Streamable HTTP, no auth, no session

{
  "mcpServers": {
    "semconv": { "type": "streamable-http", "url": "https://semconv.com/mcp" }
  }
}

Streamable HTTP with one JSON response per call. CORS is open, so an agent running in a browser can call it too.

What it looks like

You

Are the attribute keys in this service still current?

Agent calls

check_attribute_names(names: ["http.status_code", "db.statement", "service.name", "app.cart.size"])

renamedhttp.status_codeuse http.response.status_code
renameddb.statementuse db.query.text
currentservice.name
not in registryapp.cart.size

Real tool output, generated from this build's data.

8 tools

Each reads the same JSON the pages are built from, so the site and your agent cannot disagree. Open one to see the description the model is given.

search
One question in, ranked hits from everything on the site. The place to start.
What the model readsHide
Search everything semconv.com knows in one call: both attribute registries, metrics, spans, events, entities, every MUST/SHOULD/MAY in the specification and in OTLP, the OTLP wire messages and the domain pages. Takes a question in plain words ("which attribute holds the HTTP status code") or an identifier; ranks by how many terms land on ids over prose. Start here, then get_attribute or diff_versions for the full record.
list_versions
Every tracked release of each source, with dates and change counts.
What the model readsHide
List every tracked release of all three OpenTelemetry sources - semantic conventions, the specification, and OTLP - newest first, with publication dates and how many breaking, notable and editorial changes each one introduced.
check_attribute_names
Takes the keys your code emits. Reports which are renamed, deprecated or unknown.
What the model readsHide
Given attribute keys a codebase emits or queries, report which are deprecated, renamed, moved to another registry, or absent. Covers both the OpenTelemetry semantic conventions and the separate GenAI conventions registry. Use this to audit instrumentation rather than guessing from memory - the registries move every month.
get_attribute
One attribute in full, with its release-by-release history.
What the model readsHide
Full definition of one semantic-conventions attribute: type, stability, guidance note, examples, which signals carry it, and its release-by-release history.
search_attributes
Filter the registry by text, namespace, or deprecated entries only.
What the model readsHide
Search the semantic-conventions attribute registry by substring against ids and descriptions, optionally narrowed to a namespace or to deprecated entries only.
diff_versions
Every change between two releases of one source, most severe first.
What the model readsHide
What changed between two tracked versions of one source. For semconv: renames, deprecations, promotions, removals, metric shape changes. For spec: RFC 2119 requirements added, dropped, moved or restrengthened. For proto: fields added, removed, renumbered or retyped. Each ranked breaking / notable / informational.
search_requirements
Every MUST, SHOULD and MAY in the spec and in OTLP, with links to the section.
What the model readsHide
Search the RFC 2119 requirements of the OpenTelemetry specification and the OTLP protocol document - the sentences that actually bind an implementation. Use this to check behaviour against the spec rather than recalling it. Note the OTLP protocol spec is not in the specification repository; both are covered here.
get_otlp_message
One OTLP message or enum with its field numbers, types and cardinality.
What the model readsHide
One OTLP wire definition in full: every field with its number, type and cardinality, or every value of an enum. Field numbers are what binary OTLP keys on and field names are what OTLP/JSON keys on, so both matter.

Things to ask it

Copy one into your agent. Each names the tool, so the agent reaches for the server rather than its memory.

Audit the attributes a service emits
Find every OpenTelemetry attribute key this repository sets on spans, logs or metrics, then check them against semconv.com with check_attribute_names. List the ones that are deprecated or renamed, with the replacement for each, and tell me which files set them.
Prepare an upgrade
We instrument against semantic conventions v1.30.0. Use diff_versions on semconv.com to list every breaking and notable change up to v1.44.0 that touches the http, db and messaging namespaces, and say which of them affect this codebase.
Answer a spec question with a citation
Using semconv.com's search_requirements, what does the OpenTelemetry specification require of an SDK when the exporter returns a retryable error? Quote the MUST/SHOULD lines and link the section.
Name a new attribute correctly
I want to record the size of a queue in a span. Search semconv.com for existing attributes or metrics that already cover this before we invent a custom key, and recommend one.

Without an MCP client

The server is plain JSON-RPC over POST, and search is the tool to start with. Every page also has a static JSON twin an agent can fetch.

curl -s https://semconv.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"which attribute holds the http status code"}}}'

/llms.txtThe map of this surface, for a model to read first.
/api/search.jsonOne index over everything, with a type and URL per row.
/api/attributes/{id}.jsonOne attribute in full, plus its release history.
/api/renames.jsonEvery deprecated name and its successor.
/api/diff/{source}/{from}...{to}.jsonEvery change between two tracked versions.
/api/requirements.jsonEvery MUST, SHOULD and MAY in the spec and in OTLP.
/feed.xmlRSS, one entry per release.