Homi for developers

Give your agent the whole story behind the search.

A Homi collection carries the story, shortlist, comments, and decisions behind a move. With the user's permission, an agent can pick up that context and keep the search moving through typed MCP tools.

Connect Homi Open the live schema

Brooklyn Apartment Search

Example agent session

Authorized

Keep the quiet-bedroom tradeoff in mind. Which homes still fit?

collectionReadBrooklyn Apartment Search

Search story

Two people work from home. A quiet second room matters more than a larger kitchen. Evenings should feel calm.

12 saved homes4 shortlisted3 collaborators

I found four homes that preserve the quiet-room requirement. Two have new comments from the group.

Context from the user's Homi collectiontools/list

OAuth 2.1: User-approved access
MCP: Streamable HTTP
tools/list: Current function schemas
homi:all: One explicit scope

Built for agent work

Let the agent pick up where the search left off.

Homi keeps the human context beside the homes, so every tool call starts with the collection the user already understands.

Start from the story: Read why the move is happening and which tradeoffs matter before suggesting another home.
Keep the shortlist useful: Save listings, update evaluations, and carry the reasoning forward as the search changes.
Work with everyone deciding: Keep comments, locations, reactions, and next steps beside the collection they belong to.
Scout with provenance: Run saved searches and attach source links so people can check the facts behind each result.

Quickstart

Connect with OAuth 2.1 and MCP.

Homi supports Dynamic Client Registration, authorization code with PKCE, refresh tokens, and the homi:all scope. The user sees and approves the grant.

1. Discover the authorization server
Fetch the protected-resource document. Follow its authorization_servers link to the path-aware RFC 8414 metadata.
```
curl https://www.homi.so/.well-known/oauth-protected-resource
```
2. Register and authorize the client
Use the advertised registration endpoint, generate an S256 PKCE challenge, and request homi:all. Store refresh tokens as secrets.
3. Initialize MCP and request tools/list
Connect to the endpoint with the bearer token. The tools/list result contains the current unique names, descriptions, input schemas, output schemas, and safety annotations for function calling.
```
Authorization: Bearer <access-token>
MCP-Protocol-Version: 2026-07-28
Content-Type: application/json
```

Reference

Machine-readable resources

Start with discovery, then follow the live protocol documents for the current contract.

OpenAPI

Machine-readable transport, discovery, security, request, and response schemas.

/openapi.json

MCP endpoint

The canonical Streamable HTTP endpoint for Homi's typed agent tools.

/api/mcp

OAuth metadata

RFC 9728 protected-resource metadata points clients to Homi's authorization server.

/.well-known/oauth-protected-resource

Connector guide

Setup steps, privacy boundaries, supported jobs, and starter prompts.

/connectors/homi

Typed capability catalog

Use tools/list as the schema authority. These groups make the public surface easier to scan while the protocol response keeps every input and output type current.

Search context

collectionRead, collectionCreate, collectionWrite, storyRead, storyWrite, dimensionsRead, dimensionsWrite

Homes and decisions

listingsRead, listingsWrite, ingestListing, listingMediaRead, listingMediaWrite, evaluationRead, evaluationWrite

Places and collaboration

locationsRead, locationsWrite, commentRead, commentWrite, tripRead, tripWrite

Scouting

savedSearchesRead, savedSearchesWrite, scoutingRead, scoutingWrite

Consent and data boundaries

Every MCP call is bound to the Homi user in the verified access token. Agents reach only collections that user can access. Homi expects source attribution for saved listings and explicit user intent before durable writes.

Integration environment

Homi currently has one production MCP resource. Integration QA uses a separate test collection on the free plan. Standard MCP clients and the Model Context Protocol Inspector can exercise the endpoint. An isolated sandbox or packaged CLI needs a separate product release.

Errors and recovery

Status	Meaning	Recovery
400	Invalid MCP or JSON-RPC request	Validate against the negotiated protocol and tool schema.
401	Missing, expired, or invalid token	Follow WWW-Authenticate and refresh or repeat OAuth.
404	Unknown public API route	Read /api or /openapi.json for canonical paths.
429	Rate limit reached	Back off before retrying.

Public HTTP errors use JSON with a stable code, message, resolution, and documentation link. Tool-level failures also return structured content with a machine-readable code and suggested action.