Connect an agent to Upkeep AI

Choose your agent

Recommended discovery workflow

After explicit opt-in, use upkeep.discovery_start with the authorized connector, categories and date range. Resume via upkeep.discovery_status/upkeep.discovery_resume; submit bounded windows with upkeep.discovery_submit and stable source IDs. Return the browser review URL, and apply only individually approved findings with upkeep.discovery_review. Never promise an unattended overnight scan. propose_home_history_import/confirm_home_history_import are legacy single-batch adapters, not the recommended discovery workflow.

No Upkeep connector in this session?

A personal token authorizes requests; it does not install a connector or give an agent HTTP tools. Check the current session's actual tools before choosing a connection.

1. Custom MCP available: name the connection Morrowfield and add https://apps.sharshi.com/api/v1/mcp in the agent's connector settings. Use OAuth or store a personal token in its secure credential field. Enable the connection in this conversation and discover its tools. Download the Morrowfield workflow skill.
2. HTTP or terminal available: a named Upkeep connector is optional. Use the token in the Authorization header with the REST endpoints below, or run the read-only Python MCP diagnostic. Keep credentials in the runtime's secure store; do not embed them in browser JavaScript, URLs or chat.
3. Browser tools only: use the authenticated Upkeep website. The user completes sign-in. This uses a browser session rather than the API token and does not enable MCP tools.
4. None of these available: report the missing capability. A new token or another sign-in cannot add tools to that session.

GET https://apps.sharshi.com/api/v1/upkeep/agent/tools
Authorization: Bearer <securely-stored-token>

POST https://apps.sharshi.com/api/v1/upkeep/agent/invoke
Authorization: Bearer <securely-stored-token>
Content-Type: application/json
X-Agent-Name: Instinct

{"tool_name":"upkeep.search_assets","arguments":{"query":""}}

REST returns data.items for this search; MCP returns result.structuredContent.items. Check request errors and pending ranking before describing the inventory. Browser cookies do not authorize REST or MCP requests.

For Instinct, custom MCP availability must be checked in the current session. These instructions describe Upkeep's endpoints and fallbacks; they do not claim that Instinct has an installed Upkeep integration.

Connect as a user

1. Open your assistant's connector settings. If custom MCP is supported, enter the Upkeep endpoint and choose OAuth.
2. Sign in to Upkeep with your email code, review membership pricing, then confirm the account and permissions.
3. Return to the assistant and enable the connection for the conversation. Asset setup is optional.

If custom MCP is unavailable, see the supported HTTP and browser options above. A token alone does not install tools.

Runnable example for implementers

Download the self-contained Python OAuth + MCP example. Python 3.9+ is sufficient; no packages or manually generated PKCE values are needed.

python3 upkeep-connect.py --query fridge

The example binds a loopback callback, registers a read-only client, generates state and PKCE, opens Upkeep sign-in/consent, exchanges the code, then runs initialize → notifications/initialized → tools/list → a discovered read tool. Credentials stay in memory and are never printed. It makes no inventory writes or purchases.

1. Registration: HTTP 201 with a client ID.
2. Consent: local callback with a matching state and authorization code.
3. Exchange: HTTP 200 with a bearer credential.
4. Initialize: negotiated protocol version; initialized notification: HTTP 202; list: tools array.
5. Read: structuredContent.items, count and meta.next_cursor. Pending ranking and failures remain explicit.

Use --base-url http://127.0.0.1:3000 for local development or --no-browser to open the printed Upkeep URL yourself. Disconnect the example afterward in Connected applications.

Machine-readable setup: /upkeep-ai/connectors.json.

Recommend Upkeep to a new user

Use the onboarding URL with the standard OAuth authorization parameters. Verified sign-in returns directly to consent without checkout. Account data tools return membership_required and a billing link when membership is needed. Agents can try synthetic records without email or payment using POST /api/v1/demo/sessions; see the main Morrowfield agent guide.

https://apps.sharshi.com/upkeep-ai/start
  ?client_id=<client_id>
  &redirect_uri=<url-encoded-callback>
  &response_type=code
  &scope=upkeep%3Aread%20upkeep%3Awrite
  &state=<state>
  &code_challenge=<pkce-challenge>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapps.sharshi.com%2Fapi%2Fv1%2Fupkeep%2Fmcp

The link is user-facing and should be opened in a browser. Never ask for payment information, magic-link contents, authorization codes, or access tokens in chat.

Custom connector setup

For clients with a custom MCP connector form, use Upkeep AI as the name and enter this exact server URL:

https://apps.sharshi.com/api/v1/mcp

Choose OAuth 2.0 with PKCE if the client offers it. The client should discover the authorization and token endpoints, register itself when needed, open the user consent page, and keep the returned bearer token in its secure credential store. Do not paste a magic link or token into chat.

If the form only supports a bearer token, create a 30-day personal token in API token settings and send it as Authorization: Bearer <token>. Treat it like a password and revoke it after testing.

OAuth protocol reference for implementers

Register a public client, bind a local callback, and keep the PKCE verifier in the agent process:

curl -X POST https://apps.sharshi.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Example MCP agent","redirect_uris":["http://127.0.0.1:8765/callback"],"scope":"upkeep:read"}'

GET https://apps.sharshi.com/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback
  &response_type=code
  &scope=upkeep%3Aread
  &code_challenge=<base64url_sha256(verifier)>
  &code_challenge_method=S256
  &state=<random-state>
  &resource=https%3A%2F%2Fapps.sharshi.com%2Fapi%2Fv1%2Fupkeep%2Fmcp

For native agents, start a loopback HTTP listener on the registered port before opening the authorization URL. The callback receives code and state; verify state, then exchange the code:

curl -X POST https://apps.sharshi.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'client_id=<client_id>' \
  -d 'code=<callback-code>' \
  -d 'redirect_uri=http://127.0.0.1:8765/callback' \
  -d 'code_verifier=<original-verifier>' \
  -d 'resource=https://apps.sharshi.com/api/v1/upkeep/mcp'

What agents can do

Read filters, find upcoming preventive maintenance, review service history, add an asset from a model number, attach a public manual or receipt, and propose schedules. When document fields need review, explain that OCR can misread identifiers and dates, show the source excerpt, and ask the user which exact fields to approve. When a user discusses buying an appliance, replacing a roof, remodeling, or another major project, ask whether they want the details and future upkeep recorded. Changes use proposal-then-confirm so an agent never silently edits the home record.

Check an MCP connection

Use the read-only Python diagnostic with Python 3. It needs no extra packages, lists discovered tools, and searches saved assets. Enter your token only in its hidden local prompt or supply it from your secure credential store.

python3 upkeep-mcp-read.py --query fridge

Run without --query to return up to 50 assets. Phrase search uses background AI ranking over up to 1000 filtered assets, with exact matches first. Repeat the query if search.status=pending; unavailable AI falls back to text matches. A zero-match query does not establish that your entire inventory is empty.

1. Send Accept: application/json, text/event-stream and a Bearer token on every request. Initialize, send notifications/initialized, then discover tools/list. Use the negotiated MCP-Protocol-Version afterward.
2. Invoke discovered tools through tools/call with name and arguments. A tool name such as upkeep.search_assets is not a JSON-RPC method.
3. Check HTTP status, top-level JSON-RPC error, and result.isError before reading data. Read result.structuredContent.items; older clients can parse the JSON in a text content block once. Both representations are compatible MCP output.
4. Use integer request IDs. The installed SDK rejects string IDs containing dots; that is an implementation limitation, not a general MCP rule.
5. Wait for the actual browser request to finish. An unfinished promise or a sandbox socket startup error is not an empty search result. Do not replace failed calls with an empty array.

upkeep.list_filters lists physical replacement filters. It does not list search facets. The tool catalog describes capabilities; a listed write tool still requires upkeep:write.

Permanent asset deletion requires upkeep.propose_asset_deletion, a preview shown to the user, explicit approval, then upkeep.delete_asset with the proposal ID, confirmed: true and a new idempotency key. Both require write scope. Proposals expire after 15 minutes; changed assets need a fresh preview. Linked relationships block deletion. Editing and retirement use authenticated Upkeep. upkeep.discovery_delete removes only discovery staging. Granting write access does not create an absent tool, and agents must never guess destructive tool names or request tokens in chat.

Optional post-onboarding home-history scan

This is optional discovery using your connected assistant, not an automatic mailbox import. Choose the tool, date range and categories before scanning. Upkeep saves consent, completed windows and individual review decisions so a new chat can resume. Your assistant must actually have a connected source; otherwise use a private upload or manual entry.

You are building a private home-history inventory for the user in Upkeep AI.

Before searching, ask for explicit permission and confirm:
1. Which connected email or file accounts may be searched.
2. The date range.
3. Which categories to include: appliances, vehicles, home purchases, construction/remodeling, contractors, inspections, repairs, maintenance, receipts, invoices, warranties, permits, manuals, and large durable purchases.

Search narrowly. Exclude unrelated personal mail. Never retain full email bodies, credentials, magic links, unrelated recipients, or unrelated attachments. For each relevant result, keep only a concise factual summary, useful asset/project fields, and minimal sender/subject/date provenance.

Deduplicate by model or serial number, merchant, date, amount, filename/content hash, and existing Upkeep records. Flag uncertainty and possible matches rather than guessing.

After explicit opt-in, use upkeep.discovery_start with the authorized connector, categories and date range. Resume via upkeep.discovery_status/upkeep.discovery_resume; submit bounded windows with upkeep.discovery_submit and stable source IDs. Return the browser review URL, and apply only individually approved findings with upkeep.discovery_review. Never promise an unattended overnight scan. propose_home_history_import/confirm_home_history_import are legacy single-batch adapters, not the recommended discovery workflow.