MCP Integration

Lexicon Garden provides a Model Context Protocol (MCP) endpoint for AI agent integration. It covers Lexicon Garden's own features: resolving, searching, describing and validating lexicons, comparing schema versions, and finding OAuth permission sets.

The endpoint is read-only and requires no authentication — every tool can be called anonymously.

Endpoint

The MCP endpoint is available at /mcp using the Streamable HTTP transport. The home page advertises the endpoint via a <link rel="alternate"> tag for automated discovery.

Available Tools

The endpoint offers six tools.

resolve_lexicon

Resolve a lexicon by NSID the way any AT Protocol client would: find the DID named by the _lexicon TXT record of the NSID's authority, then read that DID's com.atproto.lexicon.schema record. The record comes from Lexicon Garden's index when it is there and from the network otherwise. Returns the schema, its AT-URI and CID, the authority DID, and whether it came from the index or the network. Errors name the step that failed, such as a missing _lexicon record.

  • nsid (required) — The NSID to resolve, e.g. app.bsky.feed.post
  • refresh (optional) — Read the record from the network even when it is indexed

search_lexicons

Find lexicons by what their schemas say when you don't know the NSID. Returns NSIDs with summaries and AT-URIs; follow up with describe_lexicon.

  • query (required) — Words, a quoted phrase, -word to exclude, or with semantic mode a plain description such as store a user's reading list
  • mode (optional) — keyword (default) or semantic, which ranks by meaning and falls back to keyword when unavailable
  • include_non_authoritative (optional) — Also return lexicons not published by their NSID's DNS authority (default false)
  • lexicon_types (optional) — Only these main-definition types: record, query, procedure, subscription, permission-set
  • limit (optional) — 1–20, default 10

describe_lexicon

Get detailed information about an ATProtocol lexicon schema: its definitions, authority, CID and any localized documentation.

  • lexicon (required) — The NSID to describe, e.g. app.bsky.feed.post or app.bsky.actor.profile#viewBasic for a specific fragment
  • identity (optional) — DID or handle of the lexicon authority. If not provided, the authority is resolved via DNS.
  • language (optional) — ISO 639 language code for localized descriptions from garden.lexicon.documentation records

validate_lexicon

Validate a lexicon schema and optionally validate data against it. Use this to verify schema correctness and validate records, query parameters, or procedure inputs.

  • schema (required) — The lexicon schema document
  • params (optional) — Query parameters to validate
  • input (optional) — Procedure input body to validate
  • record (optional) — Record data to validate
  • flags (optional) — Validation flags: allowLegacyBlob, allowLenientDatetime, skipExternalRefs

check_compatibility

Compare two versions of a lexicon schema and detect breaking versus non-breaking changes, with migration guidance. Supply either two schema documents (from_schema + to_schema) or an NSID with two CIDs (nsid + from_cid + to_cid).

discover_permission_sets

Discover which ATProtocol permission-set lexicon schemas cover a given set of collections and/or XRPC methods. Returns matching permission sets with their OAuth scope strings (include:<nsid>), useful for determining what OAuth scopes an application needs.

  • collections (required) — Collection NSIDs your application reads or writes
  • methods (optional) — XRPC method NSIDs your application calls

Resources

  • lexicon://browse/{prefix} — Browse the lexicon namespace tree by dot-separated NSID prefix (or empty for the root)

The server card for discovery is served over HTTP at /.well-known/mcp/server-card.

Connecting an MCP Client

To connect an MCP client (such as Claude Desktop or another AI assistant), configure it with the server URL:

https://lexicon.garden/mcp

The endpoint uses the Streamable HTTP transport and needs no credentials. Refer to your MCP client's documentation for configuration details.