Troubleshooting Spekit MCP

Experiencing issues with Spekit MCP? This guide covers the most common problems and how to fix them. Some solutions may require Account Admin access.

1. Setup and connection issues

Fixes for problems connecting or signing in.

The custom connector option does not appear

✅ 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

✅ Some tools require an admin or a specific plan.

See Spekit MCP overview for the requirements for your tool.

Sign-in fails or the connection will not authorize

✅ 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

✅ 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.

2. Using the tools

What to do when a tool call is blocked or a write does not run.

A tool call is blocked or returns a permission error

✅ 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 tool is missing from the list

✅ You only see the tools your organization has given you access to, so your list may be shorter than a colleague's. You can check which tools you have in your AI tool's connector settings.

A write did not run

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

A write failed with an error

✅ 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.

Your AI tool says the content was not found

✅ This usually means the wrong id was used, not that the content is missing. Ask your AI tool to search for the content again by name and retry with what the search returns.

Creating a Spek fails and nothing is created

✅ Every Spek has to be filed under at least one Topic that already exists. If the Topic name does not match one of yours, nothing is created. Ask your AI tool to list your Topics first, or to create the Topic before the Spek.

I cannot create a Topic at the top level

✅ Whether you can create a top-level Topic depends on your role. If yours does not allow it, your AI tool asks which existing Topic to nest the new one under. Account Admins can create Topics at the top level.

Content was created but does not look right

✅ Content is checked against your design system rules when it is created. If it does not follow them, the create is rejected and your AI tool is told what to fix. Content that skips those rules is saved as plain text instead of picking up your brand. Ask your AI tool to pull the content style guide before it drafts.

The topic hierarchy looks incomplete

✅ 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.

3. How write confirmation works

Why writes ask you to confirm, and where that step lives.

Write actions include creating new content, updating existing content, and creating a company or Deal Room. By default, each one asks you to confirm before it runs.

This confirmation is handled by your AI tool, not by a separate Spekit setting. It works through the MCP standard that both the connector and the AI tool are built on. Each tool is labeled read-only or able to change data, and the AI tool treats anything not read-only as needing your confirmation.

⚠️ Confirmation can be turned off per tool. Most AI tools let you set an individual tool to always allow, which means it runs without asking. If writes are happening without a prompt, check your connector settings for that tool. Some organizations disable the always-allow option.

Because the confirmation lives in the AI tool, we recommend confirming this behavior in your own tool during evaluation. Not every write action has been seen to prompt in every tool and session.

4. Deal Room issues

My buyer cannot open the Deal Room

✅ A Deal Room becomes viewable once you share it. Your AI tool shows you a link as soon as the room exists, but creating a room is not the same as sharing it. Open the room in the Spekit Hub (Web App) and share it from there. The connector cannot share a room, and cannot tell you whether a room has already been shared.

My buyer is asked for an email address, or is blocked

✅ Deal Room settings include access controls. "Require email address" asks viewers to enter their email before they get in, and "Limit access to" restricts the room to certain people or domains. Check both in Deal Room settings in the Spekit Hub (Web App). The connector cannot change these.

The Deal Room has the wrong logo or color

✅ Your AI tool looks the buyer up by name and may find several companies with similar names. A result marked verified is not always your buyer. Check the name as well as the mark before you confirm, and fix the branding in the Spekit Hub (Web App) if the wrong one was used.

There are now two companies for the same buyer

✅ Ask your AI tool to create a Deal Room for the buyer by name, and let it find them. If you ask it to create a company that already exists as a CRM account, you get a duplicate, and the room is not tied to the deal. Only ask for a new company when the buyer is genuinely not in Spekit yet.

I cannot tell whether the room is branded

✅ Your AI tool reports whether branding was applied at the moment the room is created. It does not report branding when you look the room up again later. Check the room in Spekit.

I need to change or remove a Deal Room's branding

✅ Branding can only be set through the connector when the room is created. To change or remove it afterwards, open the room in the Spekit Hub (Web App) and use the Branding button in Room builder.

A Spek will not go into a Deal Room

✅ Only content marked shareable in Spekit can be added to a Deal Room. Your AI tool tells you nothing was added and why.

To fix it:

1. Ask your AI tool to turn sharing on for that Spek or file.
2. Ask it to add the content again.

Account Admins, Team Admins, and Experts can change the share setting on Team Hub content. Viewers cannot, and asking through an AI tool does not change that.

Two cases cannot be fixed this way. Content imported from Confluence, Notion, or SharePoint pages cannot be shared at all. Salesforce objects and fields cannot go into a Deal Room.

A template will not go into a Deal Room

✅ A template cannot be added as a synced copy. Your AI tool tells you nothing was added. Ask it to add the template as a customizable copy instead, or leave the template out.

Content disappeared from a Deal Room

✅ Turning sharing off for a Spek or file hides it in every Deal Room and share link it is in, not just the one you were thinking about. Turn sharing back on to restore it.

The same content appears twice in a room

✅ Adding a Spek as a synced copy twice is safe, and the second request is skipped. Adding it as a customizable copy creates a new copy each time. Remove the extra copy in Spekit.

5. Current limitations

What the connector cannot do yet, and where to do it instead. We are working through what comes next based on customer feedback.

You cannot delete existing content

✅ Your AI tool can create Speks, Topics, Deal Rooms, and companies, but it cannot delete anything. To remove content, do it directly in Spekit.

Topics, companies, and Deal Rooms cannot be edited after creation

✅ 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 share a Deal Room or set its access controls

✅ Your AI tool can create a Deal Room, but it cannot share it and cannot change its access controls. A room becomes viewable once you share it from the Spekit Hub (Web App). The connector also cannot tell you whether a room has already been shared.

You cannot manage users or permissions

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

You cannot create a Slides deck yet

✅ Creating a Slides deck directly from your AI tool is coming soon. If you ask for one now, the request fails or times out rather than telling you it is unavailable. Ask your AI tool to create the content as a Spek instead, then open it in Spekit and use Present Mode.

The topic hierarchy is returned one level at a time

✅ 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.

6. Support and feedback

If you are experiencing an issue that is not listed here, you have a few ways to get help.

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

Provide feedback and track product updates

Log in with your Spekit account to access the Canny feedback board. You can submit new ideas or bug reports and vote on existing posts. You will be notified by email about status updates (Open, Planned, In Progress, Complete).

Check the Roadmap for ongoing work, and view or subscribe to the Changelog for new Spekit updates.