MCP Integration

Connect an MCP-compatible AI assistant to Goodeye and it can manage your skills, publish templates, run verifiers, and generate images from natural language.

Overview

Everything Goodeye does is reachable over MCP. Once connected, your AI assistant can:

• Design, save, fetch, and manage skills
• Publish, search, fork, and verify templates
• Deploy and run semantic verifiers
• Deploy and invoke image generators
• Upload and manage hosted images
• Manage teams, invitations, and grants
• Mint and revoke API keys
• Check your current usage and credits
• View and redeem referral codes

Agent contract: when your assistant calls get_skill or get_template and receives a body back, it executes that body as your runbook. It follows the instructions itself rather than summarizing or just displaying them.

Your skills are account-scoped, not client-scoped. Connect Goodeye in more than one client and each of them reads the same skills at the same current version, so a skill you improve in one is the skill every other one runs next. The same holds for the CLI: goodeye skills sync mirrors those skills into the directories a tool reads from disk, which covers assistants that load skill files instead of speaking MCP. See Syncing a bundle locally.

The endpoint

https://mcp.goodeye.dev/mcp

Authentication

There are two ways in.

OAuth (sign-in flow): connect in your MCP client and it prompts you to sign in. On the hosted sign-in page you can continue with your Google account or with email, and your client is authorized once you approve. Use this for interactive assistants like Claude.ai, Cursor, and VS Code.

API key: create a good_live_ key with goodeye auth create-key (or POST /v1/api-keys), then pass it as a Bearer token in your MCP client config. Use this for automated agents and CI pipelines.

Authorization: Bearer good_live_EXAMPLE_xxxxxxxx

Anonymous callers cannot use the MCP server. Public template catalog browsing is available over the REST API without auth (see REST API).

Client setup

Claude Code

Add the server with one command:

claude mcp add --transport http goodeye \
  https://mcp.goodeye.dev/mcp

This adds Goodeye to your user-level config, available in all projects. To scope it to a specific project instead, add --scope project before the server name.

To connect with an API key instead of OAuth:

claude mcp add --transport http goodeye \
  https://mcp.goodeye.dev/mcp \
  --header "Authorization: Bearer good_live_EXAMPLE_xxxxxxxx"

Claude.ai and Claude Desktop

Claude.ai and Claude Desktop share the same connectors, so you only need to set this up once.

1. Go to Customize > Connectors
2. Click Add custom connector
3. Enter:
   • Name: Goodeye
   • URL: https://mcp.goodeye.dev/mcp
4. Click Add
5. When prompted, sign in with your Goodeye account to authorize access
6. Enable the connector in any conversation via the + button

To connect with an API key on Claude Desktop, you need a bridge tool. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "goodeye": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.goodeye.dev/mcp",
        "--header",
        "Authorization:${GOODEYE_MCP_AUTH_HEADER}"
      ],
      "env": {
        "GOODEYE_MCP_AUTH_HEADER": "Bearer good_live_EXAMPLE_xxxxxxxx"
      }
    }
  }
}

Replace good_live_EXAMPLE_xxxxxxxx with your actual API key and restart Claude. This variable holds a whole header value, Bearer prefix included, which is why it is not named GOODEYE_API_KEY: the CLI reads that one as the raw key, and a prefixed value there would fail to authenticate.

Codex

Add Goodeye to ~/.codex/config.toml:

[mcp_servers.goodeye]
url = "https://mcp.goodeye.dev/mcp"

Start Codex and sign in when prompted.

A project-scoped .codex/config.toml works too, but only once you have marked that project trusted: Codex reads an untrusted project's config and leaves it switched off, so the entry is ignored with no error. Use ~/.codex/config.toml if you want Goodeye available everywhere.

To connect with an API key instead, point Codex at an environment variable holding the key:

[mcp_servers.goodeye]
url = "https://mcp.goodeye.dev/mcp"
bearer_token_env_var = "GOODEYE_API_KEY"

export GOODEYE_API_KEY="good_live_EXAMPLE_xxxxxxxx"

The variable holds the raw key with no Bearer prefix; Codex adds it when it sends the header. Current Codex releases reach remote MCP servers over HTTP with no extra setting. If Codex ignores the url entry and only starts servers it launches locally, upgrade it. Older guides mention an experimental flag for turning on remote servers; that setting has since been removed and no longer does anything, so delete it if you have it. Codex ignores keys it does not recognize, so a leftover entry causes no error, which is exactly why it is worth clearing out rather than leaving to look meaningful.

Cursor

Add Goodeye manually to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "goodeye": {
      "url": "https://mcp.goodeye.dev/mcp"
    }
  }
}

Restart Cursor after adding the config, then sign in when prompted.

To use an API key instead:

{
  "mcpServers": {
    "goodeye": {
      "url": "https://mcp.goodeye.dev/mcp",
      "headers": {
        "Authorization": "Bearer good_live_EXAMPLE_xxxxxxxx"
      }
    }
  }
}

VS Code

1. Open VS Code and press Cmd/Ctrl + Shift + P
2. Run MCP: Add Server
3. Select HTTP as the server type
4. Enter the URL: https://mcp.goodeye.dev/mcp
5. Give it the name goodeye

Or add it directly to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "goodeye": {
        "url": "https://mcp.goodeye.dev/mcp"
      }
    }
  }
}

To use an API key:

{
  "mcp": {
    "servers": {
      "goodeye": {
        "url": "https://mcp.goodeye.dev/mcp",
        "headers": {
          "Authorization": "Bearer good_live_EXAMPLE_xxxxxxxx"
        }
      }
    }
  }
}

Requires VS Code 1.99+ with GitHub Copilot enabled.

Windsurf

1. Open Windsurf and press Cmd/Ctrl + , to open Settings
2. Search for MCP or navigate to Cascade > MCP Servers > View raw config
3. Add the Goodeye server to the mcpServers object:

{
  "mcpServers": {
    "goodeye": {
      "serverUrl": "https://mcp.goodeye.dev/mcp",
      "disabled": false
    }
  }
}

4. Save and click Refresh (or restart Windsurf)
5. Sign in with your Goodeye account when prompted

To use an API key:

{
  "mcpServers": {
    "goodeye": {
      "serverUrl": "https://mcp.goodeye.dev/mcp",
      "headers": {
        "Authorization": "Bearer good_live_EXAMPLE_xxxxxxxx"
      },
      "disabled": false
    }
  }
}

Available tools

Any authenticated caller gets every tool. The groups below follow the main resource areas.

Skills

Templates

Verifiers

Note: platform-managed system verifiers are run-only via system:<name> aliases. They do not appear in list_verifiers or get_verifier, and their configuration is not exposed.

Image generators

Images

Teams and invitations

Account

Troubleshooting

"Authentication required" or 401 errors

• Try disconnecting and reconnecting Goodeye in your client settings
• Make sure you are signing in with the same account that owns your skills and keys
• If using an API key, verify the key is active and the Authorization header is formatted correctly: Bearer good_live_...

Tools not appearing

• Restart your MCP client after adding the configuration
• Verify the endpoint URL is exactly https://mcp.goodeye.dev/mcp
• In Windsurf, make sure the server is not set to "disabled": true
• In VS Code, verify GitHub Copilot agent mode is enabled (requires VS Code 1.99+)
• Check your MCP client's logs for connection errors

Budget or account errors

• budget_exhausted (402): your monthly credit grant is spent. Run goodeye usage or GET /v1/me/usage to check your balance. See Accounts and billing.
• account_suspended (403): contact hello@goodeye.dev

See also

• Getting started
• Skills
• Templates
• Verifiers
• Images
• Referrals
• REST API
• CLI
• Accounts and billing