MCP Integration

Lexicon Garden provides a Model Context Protocol (MCP) endpoint for AI agent integration. MCP allows AI assistants to browse lexicon schemas, validate data, and interact with ATProtocol services directly.

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

Five tools are available through the MCP endpoint:

describe_lexicon

Get detailed information about an ATProtocol lexicon schema, including its definition, usage examples, and 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

create_record_cid

Generate a CID (Content Identifier) for an AT Protocol record using DAG-CBOR encoding and SHA-256 hashing, following AT Protocol conventions.

  • record (required) — The JSON record object

invoke_xrpc

Call XRPC methods on your ATProtocol PDS. Supports both queries (GET) and procedures (POST). All inputs are validated against the lexicon schema before invocation. Requires authentication.

  • method (required) — The XRPC method NSID, e.g. com.atproto.repo.listRecords
  • identity (optional) — DID or handle of the lexicon authority
  • params (optional) — Query parameters as key-value pairs
  • input (optional) — Request body for procedure methods
  • atproto_proxy (optional) — Service proxy header for routing requests through your PDS to another service

facet_text

Parse rich text facets (mentions, URLs, and hashtags) from plain text. Returns AT Protocol facets with correct UTF-8 byte offsets. Mentions are resolved to DIDs when possible.

  • text (required) — The plain text to parse for facets

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

Prompts

Three guided prompts help AI agents with common tasks:

  • invoke_xrpc_guide — Provides guidance on using the invoke_xrpc tool, including method types, parameters, and service proxying. Optionally accepts a specific method NSID for targeted advice.
  • create_bsky_post — Step-by-step guide for creating a Bluesky post with rich text facets (mentions, links, hashtags). Walks through schema fetching, facet parsing, and record creation.
  • lexicon_schema_creation_guide — Comprehensive guide for creating and publishing ATProtocol lexicon schemas. Covers schema structure, validation with validate_lexicon, and publishing via invoke_xrpc with com.atproto.repo.createRecord and com.atproto.repo.putRecord. Optionally accepts an NSID for targeted examples.

Authentication

Most tools work without authentication. The invoke_xrpc tool requires OAuth 2.0 authentication, which allows the MCP client to call XRPC methods on your PDS on your behalf.

When an unauthenticated request is made to an authenticated tool, the server returns a 401 response with a WWW-Authenticate header containing the OAuth resource metadata URL, triggering the standard MCP OAuth flow.

After authenticating, you can manage your MCP settings from your identity page, including enabling access to operations like deleteRecord and applyWrites.

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. Refer to your MCP client's documentation for configuration details.

Lexicon Garden

@