Troubleshooting Spekit MCP

The custom connector option does not appear

✅ Resolution: Some tools need an extra step first. In ChatGPT, turn on Developer Mode before the custom connector option shows up. In some tools the option is admin managed, so an org admin adds the connector once for everyone.

I cannot add the connector myself

✅ Resolution: Some tools require an admin or a specific plan.

• Claude Team and Enterprise: an Owner or Primary owner adds the connector at the org level before members can connect.
• ChatGPT: write tools are limited to Business, Enterprise, and Education. Plus cannot use custom MCP connectors.
• Salesforce Agentforce: needs a Salesforce admin or developer.
• Gong: needs a Gong Tech admin role.

See Spekit MCP Overview & Setup for the requirements for your tool.

Sign-in fails or the connection will not authorize

✅ Resolution: You sign in with your existing Spekit login, not a separate account. Make sure your Spekit account is active. Confirm the server URL is entered exactly, including the /mcp path:

https://mcp.spekit.co/mcp

Gemini CLI sign-in does not open

✅ Resolution: The sign-in step opens a real browser window. It will not work over a remote SSH session or in a headless environment without local browser access. Run it where you have a local browser.

In Agentforce, the connection does not work after setup

✅ Resolution: The most common cause is a missed step. After you register the server, Salesforce creates a permission set that you must assign to the users, or the agent's running user. The connection will not work without it. If a tool call still misbehaves, inspect the mcp_request and mcp_response fields in the Agentforce builder.

A tool call is blocked or returns a permission error

✅ Resolution: Every call runs as you, scoped to your Spekit role. If a call is denied, your role may not allow that action. For example, a viewer-only user cannot create or change content, even by asking. Check your role in Spekit, or contact your Spekit admin.

A write did not run

✅ Resolution: Write actions ask you to confirm before they run. If nothing was created, you may not have confirmed the action. See section 3 below. 

A write failed with an error

✅ Resolution: When a write fails, the connector returns a real error that describes what went wrong, rather than a generic failure. Write operations are validated before anything is saved, so a failed write does not leave partial content behind. Read the error message, fix the issue, and try again.

The topic hierarchy looks incomplete

✅ Resolution: Listing your topics returns each top-level topic with its direct subtopics only. If a subtopic has its own subtopics, ask your AI tool to get that subtopic by id to load the next level. The hierarchy is returned one level at a time by design.

You cannot delete existing content

✅ Resolution: Your AI tool can create Speks, topics, deal rooms, and companies, but it cannot delete anything that already exists. To remove content, do it directly in Spekit.

Topics, companies, and deal rooms cannot be edited after creation

✅ Resolution: Existing Speks can be updated. You can change the title, body, and topic assignment. Topics, companies, and deal rooms are different. Once created, there is no way to rename or edit them through the connector.

You cannot copy an existing Spek into a Deal Room

✅ Resolution: Your AI tool can only create new content inside a deal room. It cannot attach an existing Spek from your knowledge base as is. It can draft a new version based on it, but the original stays where it is.

You cannot enable external Deal Room sharing

✅ Resolution: Your AI tool can create a deal room, but not change its sharing settings. To let buyers view the room, enable external access manually in Spekit after the room is created. The connector also cannot tell you whether a deal room already has external sharing turned on.

You cannot manage users or permissions

✅ Resolution: Your AI tool cannot add users, change roles, or change who has access to what. User and permission management stays in Spekit admin settings.

Content styling does not use Brand Studio yet

✅ Resolution: Content created or updated through the connector does not use Brand Studio yet. For fine-grained styling and layout control, use the AI Content Builder or the editor directly in Spekit.

The topic hierarchy is returned one level at a time

✅ Resolution: Listing your topics returns each top-level topic with its direct subtopics. Deeper levels need a follow-up call, rather than coming back all at once.

Contact Spekit Support

• Email: support@spekit.co
• Standard Support Hours: Monday–Friday, 7:00 AM – 4:00 PM PT
• Emergency/Outage Support: 24/7/365