FAQ

Frequently asked questions about Supaspec.

General

What is Supaspec?

Supaspec is a SaaS tool for developers who use AI coding agents. It stores versioned implementation plans (specs) that AI agents can read and write via MCP, while humans collaborate on them through a web UI.

What problem does it solve?

In AI-assisted development, the implementation spec — not the code — is the real intellectual property. Supaspec makes specs first-class: versioned, editable, searchable, and accessible to AI agents. It lets you orchestrate multiple agents on the same plan and compare their outputs.

Is it free?

Yes, Supaspec is free during the beta period. A Pro plan with additional features will be available later.

AI Agents

Which AI tools are supported?

Any MCP-compatible tool works with Supaspec, including:

  • Claude Code
  • Cursor
  • Codex
  • Windsurf
  • Copilot (with MCP support)
  • Any custom MCP client

Do I need a different config for each tool?

No. The MCP configuration is identical across all tools. One API key, one config block. Agents self-identify automatically.

How do agents identify themselves?

The MCP tool descriptions instruct agents to provide their agent_name on every write call. LLMs follow tool parameter descriptions reliably, so agents naturally comply without any special setup.

Can agents spoof their identity?

Technically yes, but since you control your own tools and API key, there's no incentive to spoof. Agent identity is a convenience feature for attribution, not a security boundary.

Specs & Versioning

How is versioning different from Git?

Supaspec versioning is inspired by Git but richer:

  • Every version has a structured commit message (summary + description + prompt)
  • Versions track which agent or user made the change
  • Proposals (suggested changes) live in the same timeline as commits
  • You can diff any two versions with full attribution

What's the difference between a commit and a proposal?

A commit applies the change immediately. A proposal saves the change for review — the section content doesn't update until you accept it. Think of proposals like pull requests for your spec.

Can I revert to a previous version?

You can view any previous version and copy its content. Direct revert functionality is planned for a future release.

Security

How is my API key stored?

Your API key is stored as a hash. The full key is shown only once when generated. We never store the plaintext key.

Can team members see each other's changes?

Yes, all project members can see all changes, versions, and agent activity within shared projects. Use project member roles (owner, editor, viewer) to control access.

Is my spec content encrypted?

Spec content is stored in PostgreSQL and protected by database-level security and access controls. Content is not end-to-end encrypted in V1.

Troubleshooting

My agent can't connect to Supaspec

  1. Check that your API key is set correctly in your MCP config (x-api-key header)
  2. Verify the key hasn't been revoked in Settings
  3. Ensure your tool is configured with "url": "https://supaspec.dev/api/mcp"

Agent changes aren't showing up

  • Agents are only registered on their first write operation
  • Check the project's Activity page for recent events
  • Verify the agent is using the correct project name or slug