Troubleshooting GravityKit MCP

Each section below starts from what you see and lists what to check. Setup steps are in Getting started with GravityKit MCP.

The assistant has no Gravity Forms tools at all #

The server lists the Gravity Forms tools only after it connects to your site with your credentials. When it can’t connect, the tools are left out of the list, and the server’s log says why.

• Quit the app completely and open it again. MCP clients read their server list when they start.
• If you installed the Claude Desktop extension, go to Settings, then Extensions, and click the extension to check its settings.
• Check that the configuration file is valid JSON, if you added the server there. A missing comma or bracket stops the client from reading it.
• For a server added through the configuration file, confirm Node.js 18 or later is installed and that npx runs from a terminal. The client starts the server with npx, so it cannot launch it otherwise.
• Read the server’s log. In Claude Desktop, an extension’s log is in its panel under Settings, then Extensions. A server added through the configuration file logs to mcp-server-gravitykit-mcp.log, in ~/Library/Logs/Claude on macOS or %APPDATA%\Claude\logs on Windows. A line saying the Gravity Forms client is unavailable gives the reason, such as failed authentication.
• Work through Authentication errors below.

Authentication errors #

• Confirm the Gravity Forms REST API is enabled: go to Forms, then Settings, then REST API, and check Enable access to the 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 account can list forms. The server reads the form list when it starts and lists no Gravity Forms tools if it can’t, and the log reports that as failed authentication. Beyond that, access follows the WordPress user’s Gravity Forms capabilities, or the API key’s permission level, so a read-only key cannot create a form.
• Check GRAVITY_FORMS_BASE_URL, or the extension’s Your website address. 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 default. Deleting forms, entries, feeds, and fields stays off until you set GRAVITY_FORMS_ALLOW_DELETE to true in the env block and restart the app. In the Claude Desktop extension, check Allow Claude to delete and overwrite your data instead. Once enabled, a deleted form or entry goes to the Trash unless a request asks for permanent removal, and a deleted feed or field is removed for good.

A product tool “is disabled on this server” #

A GravityKit product tool marked as destructive, such as gv_view_delete, stays off until you permit it. Add the tool’s name, its product prefix (gv or gmig), or all to GRAVITYKIT_MCP_ALLOW_DESTRUCTIVE, or to the extension’s Allow only some destructive tools (optional) field, then restart the app. Destructive product tools explains each option.

A request is refused with a message #

Some requests are refused with a message that names what to send instead. Two of these refusals protect your data:

• An update that would remove settings. gf_update_form and gf_update_feed replace whole lists of settings, such as a form’s notifications. When the new list leaves out a field, notification, confirmation, or setting the form or feed has, the update is refused and the message names what would be lost. Lists without IDs, such as a field’s choices, are replaced as sent. Ask the assistant to send the complete list with your change. To remove those settings on purpose, it repeats the update with the whole property named in replace, such as replace: ["notifications"]. For a single field, gf_update_field changes only that field, and gf_patch_feed changes only the feed settings it is sent.
• Card data or a password in an entry. gf_create_entry and gf_update_entry refuse a full card number, security code, expiration date, or cardholder name in a Credit Card field. They also refuse a value in a Password field, because the entries API stores both exactly as sent. Submitting the form with gf_submit_form_data masks the card number and leaves the rest out, and a card number can also be sent already masked, such as XXXXXXXXXXXX1234.

The GravityView or other GravityKit tools are missing #

• Confirm GravityKit Foundation is active on the connected site, along with the product: GravityView 3.0 or later for the gv_ tools, or GravityMigrate 2.1 or later for the gmig_ tools. These tools come from the site, so they cannot appear without the product.
• Check the WordPress version. The product tools use the WordPress Abilities API, which WordPress added in version 6.9.
• Ask the assistant to reload abilities (the gk_reload_abilities tool), or restart the app. The reply names the site the product tools use and the settings their credentials come from, and lists any ability that did not become a tool, with the reason.
• 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.
• If you set GRAVITYKIT_WP_URL, check that it names the same site as GRAVITY_FORMS_BASE_URL. When the two have different hosts, the server logs a warning naming both when it starts.
• A client that reads the tool list only once, such as Claude Code run with claude -p, can miss product tools that are still loading. Raise GRAVITYKIT_MCP_LIST_TIMEOUT_MS above its 2000 millisecond default so the list waits for them.

SSL certificate errors on a local site #

Local development tools such as Laravel Valet, MAMP, and Local WP can serve a site with a self-signed certificate, which the server rejects by default. Add this to the env block and restart:

"GRAVITY_FORMS_ALLOW_SELF_SIGNED_CERTS": "true"

"GRAVITY_FORMS_ALLOW_SELF_SIGNED_CERTS": "true"

The Claude Desktop extension has no field for this setting, so for a local site with a self-signed certificate, add the server through the configuration file instead.

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 #

If your site is slow to answer, raise GRAVITY_FORMS_TIMEOUT above its 30000 millisecond default. The GravityKit product tools use the same value unless GRAVITYKIT_TIMEOUT is set. A large entry query takes longer than a small one, so asking for a smaller page of results also helps.

The server does not retry a failed request on its own, so ask the assistant to try again once the site responds. GRAVITY_FORMS_MAX_RETRIES applies only to loading the GravityKit product tools.

Getting more detail #

Set GRAVITY_FORMS_DEBUG to true in the env block and restart. The log then records each Gravity Forms request’s method and URL, the response status, and which authentication method was selected, which shows whether calls reach your site and how they fail. Request and response bodies are not logged, and keys and secrets in URLs are masked.

Still stuck #

GravityKit MCP is open source. Report a bug or ask a question in the GravityKit MCP issue tracker on GitHub, or contact GravityKit support.