# OwnerLM MCP Server

## What is MCP?

MCP (Model Context Protocol) lets your AI assistant — Claude Desktop, ChatGPT, Cursor, Windsurf, n8n, or any MCP-compatible client — talk directly to your OwnerLM organization. Your assistant can read your properties, search documents, run agents, create deals, save memories, and generate reports without leaving the chat.

## Quick start (Claude Desktop)

1. In OwnerLM go to **Settings → Bring Your Own AI** and click **Claude Desktop**.
2. Click **Generate key**. Copy it once — it won't be shown again.
3. Click **Download claude_desktop_config.json**, or copy the JSON and paste it into Claude's config (Claude → Settings → Developer → Edit Config). Node.js is required, since the config uses `npx mcp-remote`.
4. Quit and reopen Claude Desktop. You'll see an "ownerlm" tool icon in the input bar.
5. Ask: *"Run whoami in OwnerLM"* — this confirms the connection.

Cursor and VS Code have a one-click "Add to Cursor" / "Add to VS Code" button in the wizard. ChatGPT (Pro/Team) and Windsurf use the same flow — pick the matching tile in the wizard.

## Connection details

**Endpoint**
```
https://ownerlm.com/api/public/mcp
```

**Authentication**
```
Authorization: Bearer owlm_your_api_key_here
```

**Required headers**
```
Content-Type: application/json
Accept: application/json, text/event-stream
```

**Transport**: Streamable HTTP (JSON-RPC 2.0).

## Available tools (40 total)

### Identity
- `whoami` — Confirms the connected organization, user, and client. Use this first.

### Read your portfolio
- `list_portfolios` — All portfolios in your org.
- `list_buildings` — All properties (optional `portfolio_id` filter).
- `get_building` — Full details + recent documents for one property.

### Documents
- `list_documents` — Documents for a property (optional type filter).
- `search_documents` — Semantic RAG search across documents.
- `list_extraction_schemas` — The structured extraction schemas available for a document type.
- `extract_document` — Run a structured extraction against a document and return the typed rows.

### Property and portfolio records (typed)
- `list_property_records` — Structured Debt, Entities, Insurance, Investment Memos, and Compliance rows for a building. Pass `record_type: "all"` for everything in one call.
- `list_portfolio_records` — The same typed records rolled up at the portfolio level.

### Vendor contracts
- `list_vendor_contracts` — Every service contract for a property or portfolio.
- `get_vendor_contract_terms` — Term dates, auto-renew, notice period, notice deadline, monthly cost, and the quoted termination clause for one contract.

### Rules
- `list_rules` — Active operator rules for a scope (workspace, portfolio, or building). Returns each layer so you can see inheritance.

### Property intelligence
- `get_location_intelligence` — Cached Google Places sentiment, reviews, competitor rents/snapshots, and website-change events for a building.

### AI agents
- `list_agents` — All seed + custom agents.
- `run_agent` — Trigger an agent run on a property. Returns a run_id.
- `get_agent_result` — Fetch the run result by id.

### Chat (multi-turn)
- `chat` — Send a message with full RAG context. Pass `conversation_id` from a prior response to continue the same thread.

### Skills (background automations)
- `list_skills` — All available skills (seed + custom).
- `trigger_skill` — Run a skill on demand for a property.

### Acquisitions / deals
- `list_deals` — Deals in your pipeline (optional stage filter).
- `get_deal` — Full deal record.
- `create_deal` — Add a new deal.
- `search_deal_documents` — Semantic search scoped to one deal's document set.
- `list_deal_checklist` — Diligence checklist items and their status.
- `list_deal_models` — Underwriting models attached to the deal.
- `generate_deal_memo` — Draft an IC memo grounded in the deal's documents.
- `get_deal_reconciliation` — Cross-document variances between OM, rent roll, T-12, and leases.
- `get_deal_risk` — Underwriting risk summary: occupancy, rollover, tenant concentration, diligence coverage.
- `list_deal_threads` — Document comment threads on the deal.
- `reply_deal_thread` — Post a reply to a deal thread.

### Property memory
- `save_memory` — Persist an insight so future agent runs remember it.

### PMS data (Entrata)
- `list_entrata_leases`, `get_entrata_units`, `sync_entrata`

### Reports
- `list_report_templates`, `generate_report` — returns a download URL.

### Open Knowledge Format
- `get_okf_bundle` — Returns a portable OKF v0.1 bundle (markdown + frontmatter) for a building, portfolio, or the whole tenant, including brain snippets, skills, GL canonical, property records, and rules.

### Activity & alerts
- `list_recent_activity` — Recent deals, runs, and documents.
- `list_notifications` — Your notification feed.

## Example prompts to try

- "Who am I connected to in OwnerLM?"
- "List my OwnerLM properties."
- "Search my documents for 'roof replacement' across all properties."
- "Run the Auditor agent on 123 Main St and summarize the findings."
- "Generate the monthly portfolio report for Q1 2026."
- "Create a new deal for 1200 Elm Ave, 84 units, in sourcing."
- "Remember that the boiler at 123 Main is past warranty."
- "What's new in my notifications?"

## Costs

Each tool call deducts credits from your organization. Defaults:

| Tool | Credits |
|------|---------|
| chat | 1 |
| search_documents | 1 |
| run_agent | 2 |
| generate_report | 2 |
| sync_entrata | 1 |
| trigger_skill | 1 |
| All read tools (list/get) | 0 |

When you run out of credits the tool returns `INSUFFICIENT_CREDITS` with a top-up link.

## Security

- Keys are SHA-256 hashed at rest. The raw key is shown to you only once.
- Each key is scoped to your tenant — your AI client can only see your org's data.
- Revoke any key from **Settings → Developer → API Keys**.
- All tool calls are logged in `mcp_tool_calls` with latency, status, and credits charged.
- Tools that trigger work inside OwnerLM (`run_agent`, `trigger_skill`, `chat`) run under your workspace security posture. If the posture requires sign-off, the run parks in **Waiting on you** in the app and the tool returns the run id rather than a finished result.
- Content pulled in during a run (documents, emails, scraped pages) is screened for prompt injection before it reaches the model.


## Example: Claude Desktop config

```json
{
  "mcpServers": {
    "ownerlm": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ownerlm.com/api/public/mcp",
        "--header",
        "Authorization: Bearer owlm_your_api_key_here"
      ]
    }
  }
}

Claude Desktop launches local processes from its config file, so remote servers
go through the `mcp-remote` bridge. Node.js must be installed.

## Example: Claude Code (one command)

```bash
claude mcp add --transport http ownerlm \
  https://ownerlm.com/api/public/mcp \
  --header "Authorization: Bearer owlm_your_api_key_here"
```
```

## Example: MCP Inspector

```bash
npx @modelcontextprotocol/inspector \
  --url https://ownerlm.com/api/public/mcp \
  --header "Authorization: Bearer owlm_your_api_key_here"
```