MCP Setup

Read and update cattle and sheep records from a local MCP client with Ranch.Bot. Requires Node.js 22 or newer and a Ranch.Bot account with access to a farm. The MCP package uses local stdio. Hosted connections are not public yet. ChatGPT access is a private pilot. Ranch.Bot’s Claude connector is in review; you can still connect it privately as a custom connector. Gemini has no publicly available Ranch.Bot connection.

Connection methods

Local stdio (published). The @ranchbot/mcp-server package runs on your computer and speaks stdio to a local MCP client. This is the route this guide sets up below and the only route with a public installation command.

Hosted MCP (not public yet). Ranch.Bot runs a hosted Streamable HTTP endpoint with OAuth. Hosted connections are not public yet. ChatGPT access is a private pilot. Ranch.Bot’s Claude connector is in review; you can still connect it privately as a custom connector. Gemini has no publicly available Ranch.Bot connection. There is no public click-to-connect step here.

Assistant status

Labels: Available (published route, tested for that client), Limited access (a route exists but is restricted or only partly verified), Not yet verified (no tested route for that client yet), Unavailable (not offered for that client).

The published local stdio package itself is verified at the package level; a named client still needs its own test before this guide calls it verified.

ChatGPT

ChatGPT connects only through the hosted MCP endpoint; the local stdio package does not plug into ChatGPT web. Hosted access is a private pilot, not a public connection. A private-pilot session on 2026-10-10 resolved an animal and its records, refused a write on a read-only connection, rejected a foreign farm, refreshed, reconnected, and revoked. Write and commit cases and the public listing are still outstanding, so there is no public ChatGPT connection to follow. Private success is not public installability.

Claude

Claude is two separate products; a result for one does not transfer to the other.

Claude web connector (hosted): the predefined ranchbot-claude hosted client was activated on 2026-10-14 with the callback https://claude.ai/api/mcp/auth_callback. Ranch.Bot’s Claude connector is in review and is not in Claude’s connector directory yet. You can still connect it privately as a custom connector. Ranch.Bot checked sign-in, current context, and animal and saved-record reads on 2026-10-14. Writes, refresh and revocation, cross-farm isolation, and clean-account installation are not verified.

Claude Desktop (local stdio): the published @ranchbot/mcp-server@0.2.0 package is a candidate route, and the generic stdio configuration below is published. A clean Claude Desktop run has not been recorded, so this guide does not certify the Claude Desktop client. Do not reuse this status for Claude Code.

Cursor

Not yet verified. Cursor's local MCP configuration has not been tested against the published package, and a shell or CLI fallback has not been tested either. The shell route would be CLI use, not MCP compatibility. Until a clean-client run is recorded, use CLI setup or the web app.

Replit

Not yet verified. It is not yet established which Replit product and runtime is intended, or whether a browser device login and token cache can persist in that workspace without weakening credential handling. Use the web app or a local terminal until a supported route is recorded.

Grok Bot

Not yet verified. "Grok Bot" does not resolve to one confirmed official product and environment, so no connection method is asserted and no compatibility is claimed. Generic Grok support is not substituted.

Muse

Not yet verified. The vendor and product behind "Muse" are unresolved, so no connection or submission requirements are asserted. Another "Muse" is not substituted.

Install and sign in

Open the URL printed in your terminal, sign in and explicitly approve the displayed code and requested access. No API key is needed. Keep passwords and token files out of assistant messages.

Login requests read:farms, read:animals, write:animals, read:groups, write:groups, read:records, write:records and read:exports. Farm roles still apply: Readers cannot write. These scopes do not grant farm creation or admin import access.

Version 0.2.0 supports the local stdio transport only. It removes the retired legacy API-key HTTP transport, so an older configuration that pointed the package at a self-hosted HTTP endpoint and an API key no longer works. Hosted connections are a separate, per-client surface described above and are not part of this package.

Configure your local MCP client

Use the installed command with no arguments. For clients using this JSON configuration shape:

If the client does not inherit your terminal PATH, use the absolute path to ranchbot-mcp. Restart the client after changing configuration. This generic stdio configuration does not promise compatibility with an individual assistant. Local MCP is available; a named client has not been tested here. Package and transport verification does not establish named-client compatibility.

Select a farm and read records

Ask the client to call list_my_farms. Check the farm name and ID, then call set_default_farm with that ID. Call list_animals to read the animals, or supply farm_id explicitly on a tool. For example, list the selected farm's sheep before looking up a ewe's dated records. A replacement session for a different account clears the process's selected farm. A hosted connection is bound to one farm and does not change that binding with set_default_farm.

Claude hosted connector

Ranch.Bot’s Claude connector is in review and not public yet; it is not in Claude’s connector directory. You can still connect it privately in your own Claude account as a custom connector that uses the hosted Ranch.Bot endpoint. Only sign-in and record reads have been checked.

• Endpoint: https://api.ranch.bot/mcp (Streamable HTTP)
• Client ID: ranchbot-claude (predefined public client, no client secret)
• Authentication: OAuth browser sign-in; the client supplies the predefined client ID

Prerequisites: an accessible Ranch.Bot farm, a farm role and OAuth scopes that allow the reads you ask for, and a Claude plan that allows custom connectors. Not every Claude plan or app can add one.

1. Add a custom connector in Claude using the endpoint above with client ID ranchbot-claude.
2. Sign in to Ranch.Bot, choose the farm, and review the requested scopes before consenting.
3. Begin with context and read-only record checks, and confirm the returned farm and values.

If your Claude interface requires a client secret, dynamic client registration (DCR), or Claude's published identity (CIMD) instead of the predefined public client ID, stop and contact support@ranch.bot. Do not work around it.

Ordinary writes run directly under your account permissions, bypass the app confirmation screen, and do not create the Action rows behind Change History. Read the saved record back after an uncertain write; do not assume a retry is idempotent.

Checked on 2026-10-14: sign-in, current context, and animal and saved-record reads. Writes, refresh and revocation, cross-farm isolation, and installing from a directory listing are not verified. To revoke access, use Settings → Connected Apps in Ranch.Bot; revoking from inside Claude has not been tested.

Review writes before running them

External MCP writes execute directly under your server permissions. They bypass the Ranch.Bot app's confirmation screen and do not create the Action rows behind Change History. Review the operation, farm, target and values with your assistant before authorizing a write. Read the saved record back afterwards. Never invent dates, doses or animals. If a write fails or its outcome is uncertain, check the record before deciding whether to retry. Do not automatically replay mutations.

Saving and audit boundaries

• Ordinary record writes run directly under your server permissions. They do not pause at the Ranch.Bot app confirmation screen and do not create the Action rows behind Change History. There is no server-enforced approval gate for an ordinary external write. Check the farm, target, event date, and values before you authorize it, then read the saved record back.
• Birth preview and commit are separate. A preview validates and previews without writing. Commit takes the exact producer-approved (request_id, bundle, confirmation_hash) tuple. An unchanged retry returns the already-saved event instead of writing a duplicate, and a stale or altered tuple is rejected. A matching hash is an approval attestation, not server-verified proof of a human click. This behavior is capability-dependent: check the connected release's tool list and stop if the tools are absent.
• Audit and provenance: the saved farm record is the durable evidence. External writes do not appear in the app's Action-backed Change History, which covers app and SMS writes. The absence of an Action row does not mean nothing was saved, so verify with a read.

Photo inputs: when a record or birth uses a photo, the assistant reads the printed identifier in the image. It does not read an RFID chip. Test ambiguity and corrections in your own client before relying on a photo.

Troubleshooting

• No tools or an authentication error: sign in again from your terminal (ranchbot-mcp login). A tool call does not start browser approval.
• Wrong farm or a farm-required error: call list_my_farms, confirm the farm with the operator, then pass farm_id explicitly.
• Permission denied on a write: check the farm role (Readers cannot write) and the granted scopes.
• The client cannot find ranchbot-mcp: use the absolute path to the installed binary.
• An identifier matches more than one animal: the client should ask for a disambiguator; it must not silently pick one.
• An uncertain write: read the record back before retrying, and do not replay the mutation blindly.

Evidence and last-tested

• Local stdio @ranchbot/mcp-server@0.2.0: published and clean-machine verified; production read/refresh/revoke acceptance on the exact published bytes passed 2026-10-20. Package-level evidence, not named-client certification.
• Hosted MCP with ChatGPT: private-pilot acceptance passed read-only and safety cases 2026-10-10; write cases and public listing pending.
• Named clients: ChatGPT limited (restricted pilot); Claude hosted limited (in review; private custom connector, checked 2026-10-14); Claude Desktop, Cursor, Replit, Grok Bot, and Muse not yet verified. Each needs its own clean-client test before this guide calls it verified.

Sign out and recover

Logout revokes the device session before clearing its credentials. If revocation fails, credentials remain so you can retry. Missing or expired authentication returns terminal-login instructions; a tool call does not start browser approval. Sign in from your terminal and retry the read.

The default cache is ~/.ranchbot-mcp-tokens.json, separate from CLI and admin sessions. Caches are bound to the API origin and OAuth client ID. Do not copy them between environments or print them. Stop older MCP processes before upgrading. Do not remove active .lock files.

For an older cache without environment metadata, use its original RANCHBOT_API_URL and COGNITO_DEVICE_CLIENT_ID when running logout. Provider credentials from before device sessions cannot be revoked through the device-session endpoint. Revoke them with the original provider before removing the cache; contact support if you cannot establish the original settings.

Related setup

• Assistant compatibility record for per-assistant status, limitations, and blockers.
• CLI setup for shell commands and JSON output.
• Public Agent Skill for assistant operating instructions.
• Server card for version and package metadata.
• HTTP reference for directed developer access.
• SMS and web setup for everyday livestock records.

Support: support@ranch.bot.