Skip to content

surface-ai-code/claude-plugins / plugins/surface-ai/skills/connect

connect

Verified

Connect Claude Code to Surface AI, or fix the connection. Use when the user has just installed the Surface AI plugin, when the surface MCP server's tools are missing, or when /mcp shows the surface server failed (for example a 401 or "Missing or invalid management key"). Not for adding a surface to a page — that's the surfaces skill.

Connecting to Surface AI

The plugin connects to Surface's MCP server with a management key that the user enters when they enable the plugin. Claude Code stores it securely; never ask the user to paste the key into the chat, and never write it to a file.

Check the connection

If the surface tools are available, call surface_list. Any result — even an empty list — means the connection works. Tell the user how many surfaces they have and suggest setting one up on a page of this codebase.

The tools are missing, or /mcp shows surface failed

The key is missing, mistyped or revoked. Claude Code doesn't load the tools until the key works, so walk the user through:

  1. Get a key. Open https://app.surface-ai.io/settings/developers and click Create key. It starts with mak_live_ and is shown once — copy it then.
  2. Enter it. Run /plugin, choose surface-ai, and configure it with the new key.
  3. Run /mcp to confirm surface is connected, then check the connection as above.

For anything else, point the user to https://docs.surface-ai.io/mcp/troubleshooting.

A key belongs to a user, not an organization: revoking one person's key leaves everyone else connected. If the user revoked a key under Settings → Developers, that key stops working right away.

Without the plugin

Anyone can connect without the plugin, with the key in the SURFACE_MANAGEMENT_KEY environment variable. Keep the single quotes: they store the variable rather than the key itself.

claude mcp add --scope user --transport http surface https://mcp.surface-ai.io/mcp/ \
  --header 'Authorization: Bearer ${SURFACE_MANAGEMENT_KEY}'
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall