Connect your agent

This page shows how to connect a coding agent or assistant to the Skyelight MCP server. Most agents connect with one command and a browser sign-in.

You need an owner, admin or collaborator role in a workspace. On the Pro, Team or Enterprise plan the agent gets every tool. On the Free plan the agent connects too, and can list your workspaces and projects and publish one hosted prototype. Reading feedback with an agent is on Pro. See Requirements and Plans and billing.

Install with one command

1
Run the installer
```
npx @skyelight/mcp init
```
The installer finds the coding agents on your machine and shows the change it will make to each one. It writes nothing until you confirm. It registers the remote server and leaves sign-in to OAuth, so no token is written to disk.
It supports Claude Code, Cursor, Grok, Codex and Windsurf. If it finds more than one, it asks which to set up.
Sign in the first time the agent connects
Restart the agent. The first time it calls Skyelight, it opens a browser window. Sign in to Skyelight if you aren’t signed in, and approve the connection. The agent keeps the session after that.
Ask it something
Ask “What’s open on my Skyelight project?” If you can reach more than one project, the agent lists them and asks which one you mean.

Installer options

Command	What it does
`npx @skyelight/mcp init --client <id>`	Sets up the named agent without asking which. `<id>` is `claude`, `cursor`, `grok`, `codex` or `windsurf`
`npx @skyelight/mcp init --client all`	Sets up every agent it finds
`npx @skyelight/mcp init --yes`	Writes the change without asking for confirmation
`npx @skyelight/mcp remove`	Removes Skyelight from every supported agent, asking before each change

From the app

Account Settings Coding Agents in the web app shows the installer command and a config snippet for each client. The page opens on the Free plan too, with a note on what Free includes. The snippets include the server URL and the OAuth client ID. Use them to edit a client’s config yourself. The snippets below match that page.

The server URL is:

https://app.skyelight.ai/mcp

Run:

claude mcp add -s user --transport http skyelight \
  --client-id RbF6Ga0l6S49Qsvu \
  --callback-port 54545 \
  https://app.skyelight.ai/mcp

Add to ~/.cursor/mcp.json:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "skyelight": { "url": "https://app.skyelight.ai/mcp" }
  }
}

Add to ~/.codex/config.toml:

# ~/.codex/config.toml
[mcp_servers.skyelight]
url = "https://app.skyelight.ai/mcp"
auth = "oauth"
 
[mcp_servers.skyelight.oauth]
client_id = "RbF6Ga0l6S49Qsvu"
callback_url = "http://127.0.0.1:54545/callback"

Add to ~/.grok/config.toml:

# ~/.grok/config.toml
[mcp_servers.skyelight]
url = "https://app.skyelight.ai/mcp"
enabled = true
oauth_client_id = "RbF6Ga0l6S49Qsvu"
oauth_scopes = ["profile", "email", "offline_access"]

Add to ~/.codeium/windsurf/mcp_config.json:

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "skyelight": { "serverUrl": "https://app.skyelight.ai/mcp" }
  }
}

claude.ai and ChatGPT

claude.ai and ChatGPT connect to the remote server as a custom connector. In the assistant’s settings, add a custom connector with the server URL, https://app.skyelight.ai/mcp. The assistant opens Skyelight so you can sign in and approve the connection.

With a token

Use a personal token when you can’t sign in through a browser, for example on a remote machine. The @skyelight/mcp package runs on your machine as a stdio server and sends the token with each request.

Create a personal token
Go to Account Settings API Keys in the web app and create a token. API Keys is locked on the Free plan, so on Free use the remote server with OAuth. Choose a lifetime of 1, 7, 30, 60, 90, 180 or 365 days, or no expiry. Skyelight shows the token once, so copy it before you close the dialog.

Add the server to your client

{
  "mcpServers": {
    "skyelight": {
      "command": "npx",
      "args": ["-y", "@skyelight/mcp"],
      "env": {
        "SKYELIGHT_API_URL": "https://app.skyelight.ai",
        "SKYELIGHT_API_TOKEN": "sky_..."
      }
    }
  }
}

In Claude Code, you can add the server from the command line instead:

claude mcp add skyelight \
  --env SKYELIGHT_API_URL=https://app.skyelight.ai \
  --env SKYELIGHT_API_TOKEN=sky_... \
  -- npx -y @skyelight/mcp

Set SKYELIGHT_API_URL to the app’s address without /mcp.

About tokens

A token acts as you, with your access. Keep it out of source control.
A token belongs to the organization you created it in and only reaches that organization’s workspaces.
You can hold up to 10 active tokens per organization.
Skyelight revokes your tokens for an organization when you stop holding a paid seat there, for example when you become a reviewer in every workspace or are removed. A later promotion doesn’t restore them. Create a new token.
You can revoke a token at any time on the API Keys page.

API authentication covers tokens and the API that the local server calls.

Where the local server looks for credentials

The local server checks these locations in order. For each value, it uses the first one it finds:

SKYELIGHT_API_TOKEN and SKYELIGHT_API_URL in the environment
.env.local, then .env, in the working directory
~/.skyelight/credentials, as {"apiUrl": "...", "token": "sky_..."}

Binding a repository to a project

With the local server, add a .skyelight.json file to the root of your repository. Tools then use that project when no projectId is given:

// .skyelight.json
{ "projectId": "j57abc...", "projectName": "Checkout rebuild" }

The agent can find the project ID with list_projects. The remote server doesn’t read this file. With the remote server, the agent asks for a project or calls list_projects first.

For sign-in errors and refusals, see Troubleshooting.