fabrica-mcp: Instructions file for Claude Code

Fabrica MCP Server

An MCP server giving AI agents read-only access to tokenized real property data on the Fabrica protocol.

What is Fabrica?

Fabrica tokenizes real property (land) as ERC-1155 NFTs on Ethereum. A legal trust holds title at the county level. The token controls the trust. Transfer the token, transfer ownership.

• Platform: https://fabrica.land
• Docs: https://docs.fabrica.land
• Dune: https://dune.com/fabrica/dashboard

---

Project Structure

src/
  config.ts           # Network config, contract addresses, legal notices
  index.ts            # MCP server entrypoint — registers all 11 tools
  tools/
    properties.ts     # search_properties, get_property, get_property_map
    lending.ts        # get_lending_market
    portfolio.ts      # get_portfolio
    protocol.ts       # get_protocol_stats
    scoring.ts        # explain_confidence_score
    borrowing.ts      # get_borrow_quote
    activity.ts       # get_activity
    images.ts         # get_property_image, get_portfolio_image
  clients/
    graphql.ts        # Fabrica GraphQL API client (primary data source)
    subgraph.ts       # MetaStreet pool subgraph client (dynamic pool discovery)
  types/
    index.ts          # Shared TypeScript interfaces
  __tests__/          # vitest test suite

---

Tech Stack

• TypeScript (strict mode), ESM, Node 20+
• @modelcontextprotocol/sdk (McpServer class with zod schemas, stdio transport)
• graphql-request for GraphQL clients
• tsup for building (ESM, dts: false due to TS6 deprecation)
• vitest for testing
• Not yet published to npm — installed from source

---

Data Sources

1. Fabrica GraphQL API (Primary)

Endpoint: https://api.fabrica.land/graphql (Apollo Server, public, no auth)

The Apollo API routes subgraph data internally, so all onchain and offchain property data is available through it.

Key API behaviors:

• tokens query has NO first/skip pagination. Returns all matching tokens. Pagination is client-side.
• Nested fields loans, marketplaceListings, marketplaceBids are NOT available on list queries (tokens list, wallet.tokens). Use scalar fields (supplyUnderLoan, marketplacePrice, loanOfferCount) instead. Nested fields only work on single token() queries.
• loans query requires network or networkIn — errors without one.
• loanStartedEvents, loanRepaidEvents, loanLiquidatedEvents require first! and skip! (non-nullable).
• Score is a raw integer (e.g. 73242). Kept as-is. The minScore filter expects this integer scale.
• estimatedValue is a string decimal (e.g. "396647.43"). acres is also a string.