Troubleshooting GravityKit MCP

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.

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"

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, or contact GravityKit support.