Developers

RateDeed MCP connector

RateDeed’s MCP server lets an AI assistant help a homeowner in the United States find local contractors, plan a project, and, once the homeowner links their RateDeed account, send quote requests to escrow-enabled contractors, check on them and cancel them. It follows the Model Context Protocol.

No tool moves money. A contractor answers a request with a quote; the homeowner accepts it by paying into RateDeed escrow in the app, and releases funds when they approve the work.

US only. Searches and requests need a 5-digit US ZIP code. Account tools need a free RateDeed homeowner account with a verified email.

Escrow-enabled contractors only. Requests can only be sent to contractors who have turned on RateDeed escrow payments (escrow_enabled: true).

Setup

Endpoint
https://www.ratedeed.com/mcp
Transport
Streamable HTTP (POST, JSON responses, stateless)
Protocol versions
2025-11-25, 2025-06-18, 2025-03-26
Server card
https://www.ratedeed.com/.well-known/mcp
MCP Registry
Listed in the official registry as io.github.ratedeed/ratedeed

The search and planning tools work without an account. The three account tools use OAuth 2.1. Calling one without a token returns 401 with WWW-Authenticate: Bearer resource_metadata=…, so MCP clients that support authorization start the flow automatically.

OAuth 2.1 (account linking)

  • Protected resource metadata (RFC 9728): https://www.ratedeed.com/.well-known/oauth-protected-resource/mcp
  • Authorization server metadata (RFC 8414): https://www.ratedeed.com/.well-known/oauth-authorization-server
  • Authorization code grant with PKCE (S256 required). Authorization endpoint https://www.ratedeed.com/oauth/authorize, token endpoint https://www.ratedeed.com/oauth/token.
  • Clients: public clients can register themselves (RFC 7591) at https://www.ratedeed.com/oauth/register. Confidential clients (client_secret_basic or client_secret_post) are issued by RateDeed on request.
  • Redirect URIs: https, loopback http (any port), or a reverse-domain app scheme; matched exactly.
  • Resource indicator (RFC 8707): https://www.ratedeed.com/mcp. Access tokens are bound to it and cannot be used on any other RateDeed API.
  • Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use; reusing an old refresh token disconnects the app.
  • Revocation (RFC 7009): https://www.ratedeed.com/oauth/revoke. Revoking any token disconnects the app. Homeowners can also disconnect under Profile → Connected apps; a password reset disconnects every app.

Scopes

  • quotes:read: see quote requests, their status and any quotes.
  • quotes:write: send quote requests to contractors the homeowner approves, and cancel them.

On the consent screen the homeowner chooses Send and track quote requests or Read only. A read-only connection gets 403 insufficient_scope from the write tools.

Tools

ToolClassificationScope
search_contractorsReadNone (public)
get_contractorReadNone (public)
plan_projectReadNone (public)
start_hireReadNone (public)
submit_quote_requestWrite (sensitive)quotes:write
get_request_statusReadquotes:read
cancel_requestWrite (sensitive)quotes:write

Read tools set readOnlyHint: true. The write tools set readOnlyHint: false and idempotentHint: true; cancel_request also sets destructiveHint: true. Both writes are sensitive: one shares personal details with a third party, the other cancels a request and can decline a quote. They should be approved by the homeowner every time.

search_contractors

Read · scope: None (public)

Finds contractors near a US ZIP code for a job described in plain English, ranked by a local semantic search model.

Side effects: None.

  • request (required) What needs doing, in the homeowner’s words. Max 300 characters.
  • zip (required) 5-digit US ZIP code.
  • trade Optional trade filter, e.g. Plumbers, Electricians, HVAC, Roofers.
  • limit 1–10, default 5.

Returns: matched_trades and contractors: name, slug, trade, city, state, distance_miles, rating, review_count, license_verified, escrow_enabled, profile_url.

get_contractor

Read · scope: None (public)

Returns one contractor’s profile by slug.

Side effects: None.

  • slug (required) Slug from search_contractors.

Returns: The search fields plus description, services, a review summary built only from real reviews, owner-set price range (when the owner manages the profile), phone and website.

plan_project

Read · scope: None (public)

Suggests remodel and repair projects for a space, ranked for goals and budget, with rough US cost tiers and the trades involved.

Side effects: None.

  • space (required) Part of the home, e.g. kitchen, bathroom, exterior.
  • goals What to improve, e.g. value, comfort, efficiency.
  • budget any, low (under $2.5k), mid ($2.5k–$15k), high ($15k+).
  • condition worn, fresh or unknown.

Returns: ideas with title, detail, cost_tier, cost_range, diy_friendly, trades and a ready-made search_request.

start_hire

Read · scope: None (public)

Checks whether a pro can receive a quote request, or picks up to 3 escrow-enabled pros near the ZIP for a job. For assistants without a linked account it also returns a prefilled request link the homeowner sends from RateDeed.

Side effects: None. Nothing is sent.

  • zip, project_title, project_description (required) The job.
  • trade, contractor_slug Optional.

Returns: status ready (with contractor or options and hire_url) or contact_directly (local pros and phone numbers when no escrow-enabled pro is available).

submit_quote_request

Write (sensitive) · scope: quotes:write

Sends a quote request from the signed-in homeowner to one escrow-enabled contractor and returns a request_id.

Side effects: Shares the homeowner’s name and the project details with that contractor, starts a RateDeed conversation with them, and notifies them on RateDeed (and by email unless they turned off job notifications). Nothing is charged and the homeowner is not committed to hire. The assistant must show the contractor and every field first and get approval each time.

  • contractor_slug (required) A contractor with escrow_enabled=true.
  • project_title (required) 3–100 characters.
  • project_description (required) 15–1,000 characters. No phone numbers, emails or payment details.
  • zip (required) 5-digit US ZIP code of the property.
  • category Plumbing, Electrical, HVAC & Heating, Roofing, Painting, Remodeling, Flooring, Landscaping, Carpentry, Handyman, Masonry, General Contracting.
  • timeline asap, 1-2-weeks, 1-month, flexible.
  • budget under-1k, 1k-3k, 3k-5k, 5k-10k, 10k-25k, 25k-plus, not-sure.
  • idempotency_key Recommended. Unique per request (8–200 characters, letters, digits, . _ : -). Reuse it when retrying.

Returns: request_id (e.g. QR-7K2M9QXD4T), status (pending), duplicate (true when an earlier identical request was returned instead of sending again), contractor, project, sent_at, conversation_url.

get_request_status

Read · scope: quotes:read

Shows one request (request_id) or the most recent ones, with the contractor’s quote when there is one.

Side effects: None.

  • request_id Optional. Omit to list recent requests.
  • limit 1–25, default 10, when listing.

Returns: status and status_detail; for quoted requests: quote_total_usd, card_processing_fee_usd, total_charged_usd, line_items, payment_schedule, estimated dates, expires_at and review_url; for accepted requests: the job status and amount held in escrow.

cancel_request

Write (sensitive) · scope: quotes:write

Cancels one of the homeowner’s requests.

Side effects: Notifies the contractor. If the contractor sent a quote that is still open, it is declined. Requests whose quote was accepted are jobs and cannot be cancelled here (job cancellation and escrow refunds happen in the RateDeed app). Calling it again changes nothing.

  • request_id (required) The request to cancel.

Returns: status cancelled, already_cancelled, declined_quote.

Request statuses

  • pending Sent to the contractor; no quote yet. Nothing charged.
  • quoted The contractor sent a quote. The homeowner reviews it and, to accept, pays into escrow in the RateDeed app.
  • accepted The quote was accepted and is now a job. job.status: awaiting_payment, partially_funded, funded_in_progress, completed_pending_release, releasing, completed_paid, disputed, refunded, cancelled or expired.
  • quote_declined The quote was declined by the homeowner or withdrawn by the contractor.
  • quote_expired The quote expired before it was accepted (quotes are valid for 24 hours).
  • cancelled The homeowner cancelled the request.

Prices and fees

A quote shows the contractor’s total in USD. If the homeowner accepts, the total is paid into escrow by card, and a card processing fee of 2.9% + $0.30 per charge is added at checkout; RateDeed does not keep it. get_request_status returns the total, the fee and the amount charged for each payment. Homeowners pay no RateDeed fee. Jobs of $5,000 or more are paid in three milestones (30% / 30% / 40%), each funded and released separately.

Retries and duplicates

  • Send a unique idempotency_key with each new request and reuse it on retries. A repeat returns the original request with duplicate: true.
  • Without a key, the same project sent to the same contractor within 24 hours is also treated as a duplicate.
  • If a write returns outcome_unknown, call get_request_status before retrying.
  • cancel_request is safe to repeat.

Errors

Tool errors come back as a result with isError: true, a readable message, and structuredContent: { error, message }. Authorization and rate-limit problems are HTTP errors.

  • HTTP 401 + WWW-Authenticate An account tool was called without a token, or the token expired or was revoked. The header points to the protected resource metadata; run (or refresh) the OAuth flow.
  • HTTP 403, error="insufficient_scope" The connection is read-only (quotes:read) and the tool needs quotes:write. Ask the homeowner to reconnect with send permission.
  • HTTP 429 + Retry-After Rate limit reached. Wait the given number of seconds.
  • contractor_not_escrow_ready The contractor has not turned on RateDeed escrow payments, so RateDeed cannot send them a request. Share their profile or phone instead.
  • contractor_unclaimed The listing is unclaimed (compiled from public records). The homeowner can call the business directly.
  • contractor_unverified The contractor has not verified their email and cannot receive requests yet.
  • contractor_not_found / not_found Unknown contractor slug or request ID, or a request that belongs to another account.
  • contractor_account The linked account is a contractor account; quote requests are sent from homeowner accounts.
  • own_business, blocked The homeowner cannot send a request to this contractor.
  • idempotency_key_reused The key was already used for a request to a different contractor. Use a new key.
  • daily_limit, contractor_daily_limit Per-account request limits reached (see Rate limits).
  • already_accepted cancel_request on a request whose quote was accepted. Manage the job in the RateDeed app.
  • account_suspended, email_not_verified The homeowner’s RateDeed account cannot send requests until resolved.
  • invalid_input A field is missing or invalid; the message names it.
  • outcome_unknown A write timed out or hit a server error. RateDeed could not confirm whether it went through: call get_request_status (no request_id) before retrying, with the same idempotency_key.
  • unavailable, maintenance Temporary. Retry later.

Rate limits

  • MCP endpoint, no account linked: 300 calls per 10 minutes per IP address
  • MCP endpoint, linked account: 200 calls per 10 minutes per connection
  • submit_quote_request and cancel_request: 10 per minute per account
  • Quote requests sent by assistants: 10 per account per rolling 24 hours, and 3 per contractor per account per 24 hours
  • OAuth client registration: 60 per hour per IP address
  • OAuth token and revocation endpoints: 120 per 15 minutes per IP address

Data and privacy

  • Public tools receive only the search text, ZIP code and filters.
  • Account tools use the homeowner’s RateDeed account. A quote request stores the project fields and shares the homeowner’s name and those fields with the chosen contractor only.
  • Authorization codes and refresh tokens are stored only as hashes. Access tokens are short-lived and are not stored.
  • Quote requests and connections are deleted when the homeowner deletes their account, and included in their data export.
  • RateDeed does not sell this data or use it for advertising. See the Privacy Policy.

Support

Questions or problems: support@ratedeed.com or the contact form. Privacy requests: privacy@ratedeed.com.

Also for developers: the U.S. City Home Facts API, free keyless JSON with housing, climate, trade wage and licensing data for U.S. cities.

Version 1.1.0 · Updated October 30, 2026: added account linking, submit_quote_request, get_request_status and cancel_request.