---
title: "Troubleshooting GravityKit MCP"
date: 2026-08-17
author: "Block MCP (service account)"
link: "https://www.gravitykit.com/docs/gravitykit-mcp/troubleshooting/"
---

Here are some ways to troubleshoot issues you may encounter when working with GravityKit MCP. New to the MCP? Setup steps are in [Getting started](/docs/gravitykit-mcp/getting-started/).

## The assistant has no Gravity Forms tools at all

- Restart the app. MCP clients read their server list at startup.
- Check that the configuration file is valid JSON. A missing comma or bracket makes the client skip the whole file without saying so.
- Confirm Node.js 18 or later is installed and that `npx` runs from a terminal. The server is started by `npx`, so the client cannot launch it otherwise.
- Check your MCP client's own logs for the server. A server that fails to start usually reports why there.

## Authentication errors

- Confirm the Gravity Forms REST API is enabled at **Forms → Settings → REST API**. Without it, Gravity Forms registers no REST routes and every call fails, whatever your credentials are.
- Re-check the credential pair. With an application password, the key is your WordPress *username* and the secret is the generated password — spaces included, exactly as WordPress displayed it. With an API key, the key starts `ck_` and the secret starts `cs_`; do not mix the two styles.
- Check that the user has the Gravity Forms capabilities for what you are asking. Access follows the WordPress user, or the API key's permission level — a read-only key cannot create a form.
- Check `GRAVITY_FORMS_BASE_URL`. It should be the site URL with no trailing slash and no `/wp-json` path.
- If the application password was revoked in WordPress, generate a new one. Revoking takes effect immediately.

## “Delete operations are disabled”

This is the intended default. Deleting forms, entries, and feeds stays off until you set `GRAVITY_FORMS_ALLOW_DELETE` to `true` in the `env` block and restart your app. Once enabled, deletes go to Trash unless a request explicitly asks for permanent removal.

## The GravityView or other GravityKit tools are missing

- Confirm GravityKit Foundation is active on the connected site, along with the product itself — GravityView 3.0 or later for the `gv_` tools. These tools come from the site, not from the server, so they cannot appear without it.
- Ask the assistant to reload abilities (the `gk_reload_abilities` tool), or restart the app.
- These tools authenticate with a WordPress username and application password. A Gravity Forms `ck_`/`cs_` key pair authenticates the Gravity Forms tools but not these, so set `GRAVITYKIT_WP_USERNAME` and `GRAVITYKIT_WP_APP_PASSWORD` if that is the credential you configured.

## SSL certificate errors on a local site

Local environments such as Laravel Valet, MAMP, and Local WP use self-signed certificates, which the server rejects by default. Add this to the `env` block and restart:

```
"GRAVITY_FORMS_ALLOW_SELF_SIGNED_CERTS": "true"
```

Use this for local development only. Never disable certificate verification against a production site.

## The site is on plain HTTP

Local URLs — `localhost`, `*.test`, `*.local` — work over HTTP without any extra setting. A *remote* plain-HTTP host is different: the server refuses to send Basic authentication credentials over it, because they would be readable on the network. A Gravity Forms key pair switches to OAuth 1.0a automatically and works. An application password needs `GRAVITY_FORMS_ALLOW_HTTP_BASIC_AUTH=true`, which the server accepts with a warning. Moving the site to HTTPS is the better fix.

## Requests time out or fail intermittently

Raise `GRAVITY_FORMS_TIMEOUT` above its 30000 millisecond default, and `GRAVITY_FORMS_MAX_RETRIES` above 3, if your site is slow to answer. Large entry queries are the usual cause; asking for a smaller page of results also helps.

## Getting more detail

Set `GRAVITY_FORMS_DEBUG` to `true` and restart. The log then records each request's method and URL, the response status, and which authentication method was selected — enough to see whether calls are reaching your site and how they are failing. Request and response bodies are not logged, and secrets in URLs and headers are masked.

## Still stuck

GravityKit MCP is open source. Report a bug or ask a question at [github.com/GravityKit/MCP/issues](https://github.com/GravityKit/MCP/issues), or [contact GravityKit support](https://www.gravitykit.com/support/).