Install integrations

Specra uses the dashboard and playground for reference ingestion and analysis, then exposes the resulting system through plugins and direct MCP.

1. Install the preferred integration

The preferred Specra integrations are:

• the Codex plugin
• the Claude plugin
• the Gemini plugin

The Specra plugin is available at github.com/specra-tech/plugin.

For Codex, first add the plugin marketplace from the command line:

codex plugin marketplace add specra-tech/plugin

Then install or enable the Specra plugin inside the Codex CLI plugin flow. Adding the marketplace or MCP URL alone does not install the bundled plugin skills, so make sure the plugin itself is installed in the Codex environment where you use agents.

For Claude Code, install it from the command line:

claude plugin marketplace add specra-tech/plugin
claude plugin install specra

Restart your client after installing the plugin so new sessions load the bundled Specra MCP connection and skills.

The Codex, Claude, and Gemini plugin paths are preferred because they package the right Specra MCP connection and bundled skills/workflows together.

2. Understand the opinionated agent workflow

Specra's MCP and bundled skills are intentionally opinionated about implementation.

When an agent uses the Specra generation, refinement, or evaluation workflow, it should treat TailwindCSS and shadcn/ui as the expected UI stack. In established repos, the agent should check whether those tools are already present and ask before installing anything missing. In greenfield repos, the skills default to bootstrapping with TailwindCSS and shadcn/ui instead of inventing a separate styling path.

That requirement applies to the MCP and skills workflow, not to the raw artifacts. You can still download DESIGN.md and theme.css and use them manually in another stack.

3. Sign in

For the hosted integrations, OAuth is the default flow.

After connecting, your client should prompt you to:

• sign in to Specra
• approve access for the client
• return to the client once authorization completes

If your client still needs manual bearer-token auth, generate an API token from Settings in the Specra app and use that instead.

4. Link the repo to a project

Specra integrations operate on an existing Specra project with at least one successful revision.

If your repo is tied to a project, add a root .specra.json file:

{
  "projectId": "7a4b8e9b-5f49-4b4d-a612-e870c2d529e6"
}

That lets your agent treat .specra.json as the default source of truth for project_id.

5. Direct MCP fallback

If your client does not have a preferred Specra plugin, connect it directly to:

• https://specra.tech/mcp

Example config:

{
  "command": "npx",
  "args": ["mcp-remote", "https://specra.tech/mcp"]
}

6. Use the Specra loop

The shortest useful loop is:

1. specra_load_project_context
2. generate or edit the UI in code
3. specra_validate_generated_ui
4. capture and evaluate a local preview through the plugin's implement-ui or evaluate-ui workflow when screenshot evidence is needed
5. specra_suggest_ui_fix if code-level drift needs a narrow correction

When needed, use:

• specra_get_artifact to inspect one artifact directly
• specra_map_ui_to_code to map a visible region back to source

7. Prompt the agent clearly

Good prompts:

• Build a settings page that matches this project's existing dashboard shell.
• Add a compact card grid that stays close to the extracted layout density.
• Create a topbar and sidebar that preserve this project's visual system.

Bad prompts:

• Make something cool.
• Design a whole app from scratch.
• Use this project but invent a new direction.

The rule is simple: ask for a specific UI task and tell the agent to preserve the extracted system.