Upkeep AI for Muse

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.

Access requirements

A Morrowfield account with Upkeep AI access is required. Each connection is scoped to the authenticated account. The connector requires Bearer authentication and HTTPS. No user ID is accepted in tool arguments. Standard service availability, abuse prevention, and reasonable usage limits apply.

Authentication

When Muse has an MCP connection, use the OAuth flow below. Sign-in uses a six-digit email code, with a magic-link fallback. Wait for the user to complete sign-in; do not ask for codes or links in chat. Browser sign-in alone does not authorize REST or MCP.

Use OAuth 2.0 Authorization Code with PKCE. Upkeep AI requires PKCE with the S256 challenge method, exact HTTPS redirect URI matching, and explicit user consent. Access tokens expire after one hour and refresh tokens rotate when used.

Authorization endpoint: https://apps.sharshi.com/oauth/authorize
Token endpoint: https://apps.sharshi.com/oauth/token
Revocation endpoint: https://apps.sharshi.com/oauth/revoke
Discovery: https://apps.sharshi.com/.well-known/oauth-authorization-server

Request upkeep:read for all connections and upkeep:write only when Muse will offer confirmed changes. Send access tokens only in the HTTP header below. Credentials must never be placed in prompts, URLs, tool arguments, or logs.

Authorization: Bearer <oauth-access-token>

For clients that cannot run OAuth, ask the user to create a personal token from API token settings. Personal tokens are account-scoped, expire after 30 days, and should be stored in the client credential store.

Authorization: Bearer <personal-api-token>

Write requests should also provide a stable retry key:

Idempotency-Key: <caller-generated-key>
X-Agent-Name: Muse

Implementer reference

For a runnable PKCE and MCP lifecycle example, see the Python connection example. User connection steps are described above.

Dynamic client registration

MCP clients can register a public OAuth client without a pre-issued client ID:

POST https://apps.sharshi.com/oauth/register
Content-Type: application/json

{"client_name":"My MCP agent","redirect_uris":["https://agent.example/callback"],"grant_types":["authorization_code","refresh_token"],"response_types":["code"],"token_endpoint_auth_method":"none","scope":"upkeep:read"}

The response includes client_id. Redirect URIs must use HTTPS, or HTTP only for loopback development callbacks on localhost, 127.0.0.1, or ::1. Register the exact callback URI your client listens on, start that listener before opening authorization, and verify state before exchanging the code.

Tools and permissions

The connection is named Morrowfield. Upkeep advertises six natural-language workflow tools; the shared Morrowfield endpoint adds Tasks as the seventh. These detailed actions are available dynamically inside the workflows and remain callable by existing clients.

Write safety and side effects

Read tools do not change inventory; invocations are audited. upkeep.propose_asset records a reviewable proposal and returns a proposal ID. It must not be described as a completed addition. upkeep.confirm_asset creates one home, vehicle, or equipment record and requires the proposal ID, explicit user approval, and an idempotency key. Safe retries return the original result instead of creating a duplicate.

Data returned

Results use opaque record IDs and ISO 8601 dates. Maintenance results may include priority, estimated time, safety classification, instructions, and evidence from a stored document. Muse should preserve source titles and quotes when explaining a recommendation.

Status and errors

MCP requests return standard JSON-RPC results and errors. Authentication failures return HTTP 401 with protected-resource discovery metadata. Missing permissions return HTTP 403 or a scoped MCP tool error. Accounts without current access return HTTP 402. Invalid tool input or unavailable records return a tool error without completing the requested write. Callers must not claim success unless the tool result confirms it.

Example requests

POST https://apps.sharshi.com/api/v1/upkeep/mcp
Accept: application/json, text/event-stream
Authorization: Bearer <access-token>
Content-Type: application/json

{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}

• “Any filters I need to replace?”
• “What preventive maintenance should I do this week?”
• “Add the fridge I just bought to Upkeep AI.”
• “Figure out the maintenance schedule for this model and keep it updated.”
• “I replaced the filter today. Record it and tell me when it is due again.”

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.

Support and policies

Users can review and revoke access from Connected applications. Connector questions may be sent to [email protected]. Use of the connector is governed by the Terms of Service and Privacy Policy.