Troubleshooting

Fixes for the common snags: stale tool schemas and old clients, OAuth loops, clients asking for credentials, tasks that never start, stale decisions, webhook handshakes and rate limits.

Tools look stale, or the client says the server is incompatible#

Simp's MCP server speaks the 2026-07-28 protocol only, at https://voice.simpmobile.com/mcp. It replaced the earlier server on 2026-10-05; the old URLs (/api/mcp/v1 and /api/mcp) are gone.

Remove the Simp connector in your client and add it again with https://voice.simpmobile.com/mcp.
tools/list carries ttlMs and cacheScope: a current client refreshes the list on its own once the hour is up.
A client that still opens with initialize gets HTTP 400 with -32022 naming the supported version (2026-07-28). Update the client.

The client asks for a client ID and secret#

The client does not support Client ID Metadata Documents. Simp no longer offers dynamic client registration (the MCP specification deprecated it on 2026-07-28). Options, in order:

Make sure you pasted the full URL and that the client is a current MCP client using the Streamable HTTP transport. ChatGPT, Claude and Claude Code identify themselves with a metadata document and need no credentials.
If you build the client yourself, host a metadata document and use its URL as your client_id (see Authentication).
Pre-registered credentials exist for an installation that can do neither; ask through your usual Simp contact.

Sign in (or sign up) and the approval screen follows straight after - the connection resumes where it left off. If it stalls, start the connection again from your client. If your browser blocks third-party cookies aggressively, allow them for Simp during the sign-in.

The OAuth flow loops or fails with invalid_grant#

invalid_grant on refresh: your refresh token was already rotated and replayed, or the user disconnected the app. Reuse revokes the whole grant, by design. Start a fresh authorisation. Persist the new refresh token before using it.
invalid_request mentioning code_challenge: public clients must send PKCE; only S256 is accepted.
Redirect URI mismatch: matching is exact apart from loopback ports. Register the exact URI your client uses.
invalid_scope: an unknown scope value, or a scope outside what the client registered.
iss does not match: every authorization response carries iss equal to the metadata issuer; compare by exact string. A mismatch means the response did not come from the server you started with, so discard it.
invalid_grant on a connection made before 2026-10-05: codes and tokens are now bound to the issuer and the resource that minted them, and older ones carry neither. Connect again.
invalid_target: the resource parameter does not name https://voice.simpmobile.com/mcp.

The task never starts#

Almost always: it is waiting for approval. create_task returned status: "awaiting_approval" and an approval_url; the user has an hour to tap Approve in the Simp app. On rights_based connections a task outside the granted rights also waits for approval - that is the fallback working, not a failure. Check get_task: a current_state of awaiting_approval means exactly that.

A get_answer, send_update or follow_up task that is approved can still wait: Simp contacts people only between 08:00 and 21:00 in their own local time. See Deadlines and timing.

Other causes, each with its own teaching error at create time: plan minutes used up (ai_minutes_cap_reached), a destination the policy does not allow (destination_not_allowed), a frozen connection (connection_frozen), the connection's daily cap (connection_daily_cap_reached). See the Errors catalogue.

respond_to_decision came back with not_awaiting_input#

The decision already resolved - the user answered in the Simp app, the hold timed out, or the call ended. Call get_task again and act on the current state. A decision_id is only valid while it appears in pending_decisions.

My webhook never activates#

The registration is pending_verification until your endpoint completes the ownership handshake: echo { "challenge": ... } with a 2xx, or POST it to verify_url within five minutes. Re-send the challenge from Connected apps.
Private or local addresses are rejected (no localhost, no tunnels that resolve privately). Use a public HTTPS endpoint with a valid certificate on port 443.
Redirects are not followed; respond 2xx directly.
Signature failing? Verify over the raw body bytes, not a re-serialised JSON object, and check your clock (5-minute skew limit).

Rate limited#

rate_limited carries retry_after_seconds. Per user and client: 60 tool calls and 20 task creations a minute; newly registered clients also have conservative platform-wide ceilings until raised. See Rate limits.

How do I disconnect an app?#

In Simp: Profile, Connected apps, pick the app, Disconnect. That revokes every token the app holds immediately; it must go through consent again to reconnect.

Can an integration contact people without the user knowing?#

No. On the default mode every task waits for the user's approval, which expires after an hour. If the user moves a connection to notify_only or rights_based, every auto-dispatched task still starts with a push naming the app, shows in Activity, and can be cancelled - and sharing beyond the envelope they agreed still comes back to them for approval. See Permission modes.

Still stuck?#

Reach us through your usual Simp contact with the task_id or the event_id and the time - every tool call, token event and webhook attempt is logged on our side.