> ## Documentation Index
> Fetch the complete documentation index at: https://formpaste.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting the MCP server

> Fix connection failures, auth errors, scope denials, and missing tools when connecting an agent to Formpaste.

Most MCP problems fall into a few buckets. Match the symptom to the cause below.

| Symptom                                   | Likely cause                                           | Fix                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Client can't connect / connection refused | Wrong endpoint host                                    | The endpoint is `https://api.formpaste.com/mcp` (note `api.`, not `app.`).                                                                             |
| Tool call returns `unauthorized`          | Missing, mistyped, or revoked token                    | Re-mint a token under **Settings → API & MCP** and update your client config. The token is shown once.                                                 |
| A read tool returns `forbidden`           | A setup-scoped token called `list_submissions`         | Setup tokens cannot read submissions. Use a full-access token, or mint one. See [API tokens](/docs/agents/api-tokens).                                      |
| Tool call returns `not_found`             | Wrong `formId`, or a form owned by a different account | Call [`list_forms`](/docs/agents/list-forms) to get valid ids for the token's account.                                                                      |
| `formpaste` not listed after install      | Client not restarted, or stale `mcp-remote`            | Restart the client. If it persists, clear the `mcp-remote` cache (`npx clear-npx-cache`) and reconnect.                                                |
| Only three tools show                     | An old cached connection                               | Reconnect - the current server exposes six tools (`create_form`, `get_snippet`, `list_forms`, `get_form`, `send_test_submission`, `list_submissions`). |

## The error shape

Every tool error is a JSON object an agent can branch on:

```json theme={null}
{ "error": { "code": "not_found", "message": "No form with that id on your account.", "hint": "Call list_forms to see your form ids." } }
```

The `code` is one of a fixed set: `unauthorized`, `forbidden`, `not_found`, `invalid_input`,
`invalid_framework`, `too_many_fields`, `field_too_large`, `internal_error`.

<CardGroup cols={2}>
  <Card title="Install" icon="download" href="/docs/agents/install">
    Per-client install commands.
  </Card>

  <Card title="API tokens" icon="key" href="/docs/agents/api-tokens">
    Full vs setup token scopes.
  </Card>
</CardGroup>