# HYBRD MCP setup for Instinct

You are Instinct. A person asked you to connect to HYBRD. Follow every step in order. Do not claim the connection works until an authenticated get_account tool call succeeds.

Instinct has no persistent native MCP client. Do not stop because there is no “add MCP endpoint” UI, and do not automate the HYBRD web app. You must perform OAuth and MCP JSON-RPC over HTTP yourself.

## What this connection does

HYBRD gives the person’s approved AI access to their profile, workouts, plans, health context, and connected fitness integrations. After setup, use the server’s tools/list response as the authority for available tools and arguments.

## Server contract

- MCP resource and endpoint: https://mcp.hybrd.com/mcp
- OAuth metadata: https://mcp.hybrd.com/.well-known/oauth-authorization-server
- Client registration: https://mcp.hybrd.com/register
- Device authorization: https://mcp.hybrd.com/device_authorization
- Token: https://mcp.hybrd.com/token
- Revocation: https://mcp.hybrd.com/revoke
- Transport: streamable HTTP using JSON-RPC 2.0

## Rules specific to Instinct

- Treat authentication as valid only for the current Instinct conversation/session. Separate shell commands are parts of that same session.
- Do not promise cross-session persistence. Instinct currently has no verified encrypted store that can return a secret to later shell commands.
- Never print, trace, attach, or put access_token, refresh_token, Authorization, or the private device_code in chat or logs.
- Keep the client_id with the token pair. The client_id is not a secret, but it is required for revocation.
- Keep diagnostic logs separate from secret files. Log timestamps, endpoint names, HTTP status, request IDs, and OAuth error names only.

## Step 1: create private session storage

Create one private temporary workspace before the first request:

```sh
umask 077
workdir="$(mktemp -d)"
chmod 700 "$workdir"
printf %s "$workdir" > "$HOME/.hybrd-instinct-workdir"
chmod 600 "$HOME/.hybrd-instinct-workdir"
```

At the start of every later shell command, reload it with workdir="$(cat "$HOME/.hybrd-instinct-workdir")". Do not rely on shell variables surviving when a command exits. The pointer file contains only the workspace path, not a token, and must also be deleted during cleanup.

Files created under this workspace use permission 0600: only the current Unix user can read or write them. They are still plaintext, so this is a session-only fallback—not durable secure storage. Revoke the token and delete the workspace when the Instinct session is finished.

Persist client_id, device_code, the device-code issue time, expires_in, interval, and the eventual token response before the command that received each value exits.

## Step 2: discover OAuth

GET https://mcp.hybrd.com/.well-known/oauth-authorization-server.

Read the registration_endpoint, device_authorization_endpoint, token_endpoint, and revocation_endpoint from the response. They should match the server contract above. Stop and report the mismatch if they do not.

## Step 3: register an Instinct client

POST https://mcp.hybrd.com/register with Content-Type: application/json and this body:

```json
{
  "client_name": "Instinct",
  "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
  "token_endpoint_auth_method": "none",
  "redirect_uris": [],
  "response_types": []
}
```

Save the full response as $workdir/registration.json with permission 0600 before reading client_id. Reuse a registration only while its saved client_id remains available; otherwise register a new client.

## Step 4: request device authorization

Reload client_id from the saved registration response. Send the form with curl --data-urlencode so no trailing newline becomes part of the resource value:

```sh
curl --fail-with-body -sS -X POST https://mcp.hybrd.com/device_authorization \
  -H Content-Type:application/x-www-form-urlencoded \
  --data-urlencode client_id=$client_id \
  --data-urlencode resource=https://mcp.hybrd.com/mcp \
  -o $workdir/device.json
chmod 600 $workdir/device.json
date +%s > $workdir/device-issued-at
jq -jr .device_code $workdir/device.json > $workdir/device-code
jq -r .interval $workdir/device.json > $workdir/poll-interval
chmod 600 $workdir/device-code $workdir/poll-interval
```

Omitting scope requests all published MCP scopes. Send a space-delimited scope only when the person asked for a subset.

Do not use echo or a printf format ending in a newline with curl --data-binary. HYBRD compares the decoded resource exactly; a final LF changes the value and causes invalid_request.

The response contains private device_code plus user-facing user_code, verification_uri, optional verification_uri_complete, expires_in, and interval. Do not display the full response.

## Step 5: show approval and poll immediately

1. Calculate and state the exact expiry time from the saved issue time plus the returned expires_in. Do not assume five minutes.
2. Give the person verification_uri_complete when present. Otherwise give verification_uri and user_code.
3. Send a separate chat message containing only user_code so it is easy to copy.
4. Start polling immediately. Do not wait for the person to say “done”; approval and polling happen concurrently.

POST https://mcp.hybrd.com/token as application/x-www-form-urlencoded with grant_type=urn:ietf:params:oauth:grant-type:device_code, the saved device_code, client_id, and resource=https://mcp.hybrd.com/mcp. Use --data-urlencode for every field.

Poll once per returned interval. authorization_pending is normal. slow_down means increase the delay. expired_token or access_denied means stop; never reuse that device_code.

Instinct shell commands may be killed after about 120 seconds. Poll in batches no longer than 90 seconds:

- Before each batch, reload all state from the private workspace and calculate the real device-code deadline.
- Redirect every token response to a 0600 file; do not let curl print it.
- Inspect only the error name or whether access_token exists. Never print the token response.
- If a batch ends with authorization_pending and the code has not expired, immediately start another batch using the same saved device_code.
- A shell timeout is not an OAuth failure and must not silently end polling.
- On success, save the complete access/refresh token response before the polling command exits.

Use this 90-second batch pattern. It prints status words only, never secrets. Run it again immediately when it prints POLL_BATCH_PENDING:

```sh
workdir="$(cat "$HOME/.hybrd-instinct-workdir")"
client_id="$(jq -r .client_id $workdir/registration.json)"
issued_at="$(cat $workdir/device-issued-at)"
expires_in="$(jq -r .expires_in $workdir/device.json)"
expires_at=$((issued_at + expires_in))
batch_ends=$(($(date +%s) + 90))
while [ "$(date +%s)" -lt "$expires_at" ] && [ "$(date +%s)" -lt "$batch_ends" ]; do
  interval="$(cat $workdir/poll-interval)"
  curl -sS -X POST https://mcp.hybrd.com/token \
    -H Content-Type:application/x-www-form-urlencoded \
    --data-urlencode grant_type=urn:ietf:params:oauth:grant-type:device_code \
    --data-urlencode device_code@$workdir/device-code \
    --data-urlencode client_id=$client_id \
    --data-urlencode resource=https://mcp.hybrd.com/mcp \
    -o $workdir/token-poll.json
  chmod 600 $workdir/token-poll.json
  if jq -e ".access_token and .refresh_token" $workdir/token-poll.json >/dev/null; then
    mv $workdir/token-poll.json $workdir/tokens.json
    chmod 600 $workdir/tokens.json
    echo TOKEN_READY
    exit 0
  fi
  error="$(jq -r '.error // "unexpected_response"' $workdir/token-poll.json)"
  case "$error" in
    authorization_pending) ;;
    slow_down) interval=$((interval + 5)); printf %s "$interval" > $workdir/poll-interval ;;
    *) echo "TOKEN_POLL_STOPPED:$error" >&2; exit 1 ;;
  esac
  sleep "$interval"
done
if [ "$(date +%s)" -ge "$expires_at" ]; then
  echo DEVICE_CODE_EXPIRED >&2
  exit 1
fi
echo POLL_BATCH_PENDING
```

These examples use jq. If jq is unavailable, use another JSON parser with equivalent file-based, no-secret-output behavior; never replace it with cat on a secret response.

## Step 6: initialize MCP

Reload access_token from the private token file for each MCP command. Never print it. Every request goes to the MCP endpoint and uses these headers:

- Authorization: Bearer followed by the access token
- Content-Type: application/json
- Accept: application/json, text/event-stream

First send initialize and save both response headers and the complete body:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"Instinct","version":"1"}}}
```

Read protocolVersion from the initialize result. Save any Mcp-Session-Id response header. On every later request, send MCP-Protocol-Version with the negotiated version and send Mcp-Session-Id if the server returned one.

Then send the initialized notification:

```json
{"jsonrpc":"2.0","method":"notifications/initialized"}
```

Then list tools:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

Save the full tools/list response body to a file before parsing or summarizing it. It can exceed Instinct’s output-capture limit and may be JSON or an SSE data event. HTTP 200 with truncated terminal output does not mean the server returned an incomplete catalog. Never rely on a remembered tool count.

## Step 7: verify the account with tools/call

Use the authoritative tools/list schema to call get_account:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_account","arguments":{}}}
```

Show the returned email and ask the person to confirm it is the intended HYBRD account before making writes. Also report granted scopes and subscription status. Do not claim setup succeeded before this call works.

After confirmation, call get_profile, complete required onboarding TODOs using their toolName values, and call list_workouts to summarize recent training.

## Step 8: end the Instinct session safely

Instinct cannot currently retrieve its saved token in a later conversation. Before the current session ends:

1. POST https://mcp.hybrd.com/revoke with the saved refresh token and client_id. Revoking either token revokes the pair.
2. Verify the old access token no longer authenticates.
3. Delete the private workspace and the $HOME/.hybrd-instinct-workdir pointer file.
4. Tell the person that a future Instinct session must run device authorization again.

Do not revoke merely because one shell command ended; revoke when the Instinct conversation/task is actually finished or the person asks to disconnect.

## Instinct troubleshooting

- invalid_request mentioning resource: rebuild the form with --data-urlencode and the exact MCP URL. Check for a trailing LF or whitespace. Do not retry the same malformed bytes.
- expired_token before approval was observed: request a new device code, show its new link and code, and begin polling immediately.
- Polling command was killed: if the saved device code is still before its calculated deadline, resume another short batch. Otherwise request a new code.
- Token endpoint returned HTTP 200 but MCP cannot authenticate: confirm the successful token body was saved before the command exited and load access_token from that file without printing it.
- Vault write succeeded but a later shell cannot read it: the vault is not usable programmatic persistence. Continue only with current-session 0600 storage; do not claim future sessions are connected.
- initialize worked but later MCP calls fail: send notifications/initialized, the negotiated MCP-Protocol-Version, and the saved Mcp-Session-Id when present.
- tools/list output ends mid-schema: parse the saved complete response file, not terminal or tool output capture.
- get_account shows the wrong email: make no writes. Revoke the token, delete session secrets, and repeat authorization with the intended account.
- Any secret appeared in chat or logs: revoke immediately, delete the exposed material, and start a new authorization.
- For any OAuth error not listed here, follow error_description instead of guessing.

## Related

- General connection skill: https://hybrd.com/resources/mcp-setup/skill.md
- Token refresh details: https://www.hybrd.com/resources/mcp-token-refresh/skill.md
- General MCP troubleshooting: https://www.hybrd.com/resources/mcp-troubleshooting/skill.md
- Human setup page: https://www.hybrd.com/mcp