MCP developer reference

Use the hosted, read-only MCP endpoint to add permitted EasyAgentIDX data to an AI workflow. Existing REST APIs remain the interface for application writes and broader platform resources.

Endpoint and transport

https://app.easyagentidx.com/api/mcp

Streamable HTTP with per-request, stateless servers. POST supports discovery and tool calls. Persistent GET streams, session DELETE, batches, subscriptions, sampling and elicitation are not supported. The maintained SDK handles current protocol traffic with JSON results and stateless 2025-era compatibility with finite SSE results. Current clients supply the standard protocol, method and tool-name headers alongside the per-request metadata envelope.

Authorization

OAuth authorization code with PKCE S256 and resource-bound tokens. This is a human-authorized connection, not an API-key or machine-to-machine endpoint. Client metadata discovery and dynamic registration are supported by the maintained provider.

• Resource: https://app.easyagentidx.com/api/mcp
• Issuer: https://app.easyagentidx.com/api/auth
• Resource metadata: /.well-known/oauth-protected-resource/api/mcp
• Authorization metadata: /.well-known/oauth-authorization-server/api/auth
• Access token lifetime: 5 minutes.
• Rotating refresh tokens and connection authorization: up to 30 days.

Discover authorization, token, registration and JWKS addresses from metadata. Request platform:read plus the categories your workflow uses. Request offline_access only when ongoing access is needed. The consent screen can narrow requested scopes.

Read-only tool catalog

Tool inputs

• get_capabilities: no arguments. Returns the selected website, permitted tools and shared quota.
• search_listings: optional location, min_price, max_price, min_beds, max_beds, min_baths, property_type, status, sort, page and per_page. Status defaults to active and sort to newest. Schemas enumerate supported status and sort values.
• get_listing: listing_id.
• list_leads: page, per_page, optional status and name filter q.
• get_lead: lead_id. Contact fields and notes default to omitted. Set include_contact or include_notes explicitly when needed. Returns a linked visitor_id where available.
• get_saved_activity: visitor_id, page and per_page. Requires both saved-search and saved-listing read scopes and a linked permitted lead.
• list_valuation_reports: page and per_page.
• get_valuation_report: report_id.
• get_analytics: days from 1 to 90, default 30.

Tool discovery returns strict input schemas. Unknown fields are rejected. Paginated calls default to 10 items, allow up to 20, and stop at page 50. Result content is bounded. Listing photos, remarks and feature arrays are intentionally reduced for AI context.

Authorization boundaries

Signature, issuer, audience, expiry and scope are validated before tools run. Every call also checks the immutable user, account, website and feed grant against current database state. Tool discovery is filtered to that connection’s current permissions.

Lead access is account-scoped and source-website-scoped. Assigned agents only receive assigned leads. Saved activity must be linked to one of those leads. Valuation reports must belong to the selected website’s active add-on and are withheld from assigned-only roles because existing reports do not provide an agent-assignment boundary.

MCP requires at least one MLS board approved through the customer’s EAI account. The selected website must have an active approved feed. This reuses existing EAI approval and activation, with no MCP-specific approval record. Every connection stays bound to that website and feed. HomeThread, billing, account administration, white-label configuration, agency provisioning and writes are not in this tool set.

Response semantics

Listing results retain MLS attribution and source update metadata. retrieved_at is when EasyAgentIDX served the result, not the MLS update time. Existing report reported_at is its original date. Listing URLs are returned only when a configured HTTPS listing page matches the approved website. Otherwise listing_url is null. Saved listing IDs must be resolved through current authorized listing access before display.

Website analytics are existing event counts, not regional market statistics. Missing or unknown values must remain unknown. Remarks, lead notes and names are untrusted data, never instructions.

Limits and errors

Requests are capped at 32 KiB with a 20-second execution deadline. Tool payloads remain under 128 KiB, with a 256 KiB total response cap. REST and MCP share account-and-website capacity. Production traffic controls fail closed if Redis is unavailable.

HTTP authorization errors use the standard discovery or scope challenge. Tool failures return isError with a bounded code such as NOT_FOUND, INSUFFICIENT_PERMISSION, VALUATION_ACCESS_REQUIRED or TOOL_UNAVAILABLE. No internal error details are returned.

For account setup and consent, see the customer connection guide. For application workflows, use the REST API reference.