> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Corelayer MCP Server

> Connect AI agents and MCP-compatible tools to Corelayer issues, integrations, and organization memory.

## Overview

The Corelayer MCP server lets AI agents access Corelayer through the Model
Context Protocol (MCP). Agents can discover Corelayer groups, list issues, read
issue details, inspect summaries, search organization memory, and use that
context in their normal workflows.

Use Corelayer MCP when you want an AI tool to answer questions like:

* "What are the highest-priority open production issues right now?"
* "Search our Corelayer memory for previous decisions about this incident."
* "Find issues in the workspace, then create tickets or daily summaries in my
  planning tool."

Corelayer supports two MCP connection modes:

| Mode       | Best for                                        | Install required? |
| ---------- | ----------------------------------------------- | ----------------- |
| Remote MCP | Hosted connectors, team workflows, web agents   | No                |
| Local MCP  | Coding agents that run local stdio MCP commands | Yes, via `npx`    |

For most hosted connectors, use the remote MCP endpoint:

```text theme={null}
https://api.corelayer.com/mcp
```

## Remote MCP

Remote MCP is the easiest way to connect a hosted AI agent or connector to
Corelayer. The agent talks to Corelayer over HTTPS and authenticates with a
Corelayer API key.

Remote MCP requires an MCP host that supports HTTP MCP servers and bearer-token
authentication. If your host only supports local stdio MCP servers, use the
local package below.

Use this connection shape in MCP clients that support remote HTTP servers:

```json theme={null}
{
  "mcpServers": {
    "corelayer": {
      "url": "https://api.corelayer.com/mcp",
      "headers": {
        "Authorization": "Bearer cl_key_..."
      }
    }
  }
}
```

Some MCP hosts use `serverUrl` instead of `url`, or collect the bearer token in
a separate authentication field. Use your host's MCP configuration format, but
keep the same endpoint and authorization header.

Remote MCP currently exposes read-only tools. It does not expose close, reopen,
or bulk close operations.

## Authentication

Create a dedicated API key for your MCP connector:

```bash theme={null}
corelayer api-keys create --name "Corelayer MCP"
```

Use the returned key as the bearer token:

```text theme={null}
Authorization: Bearer cl_key_...
```

Use a dedicated key per connector or automation. This makes it easier to audit,
rotate, and revoke access without disrupting other workflows.

## How Connectors Find a Group

Most Corelayer tools are scoped to a group. A connector does not need to know
the `groupId` before setup.

The normal connector flow is:

1. Call `corelayer.list_groups`.
2. Let the agent pick the matching group by name, or ask the user to choose.
3. Pass the selected group's `id` as `groupId` to group-scoped tools.

For example, an agent instruction can say:

```text theme={null}
First call corelayer.list_groups to find the Corelayer group for this
workspace. Use the group whose name matches this team. If more than one group
looks relevant, ask me which one to use. Use that groupId for future Corelayer
calls.
```

This is the recommended pattern for hosted connectors because it avoids asking
users to copy internal IDs during setup.

## Available Remote Tools

| Tool                          | Type | Description                                                                      |
| ----------------------------- | ---- | -------------------------------------------------------------------------------- |
| `corelayer.list_groups`       | Read | List Corelayer groups the API key can access.                                    |
| `corelayer.list_issues`       | Read | List issues for a group with filters and pagination.                             |
| `corelayer.get_issue`         | Read | Fetch detailed issue context, root cause, trace, and metadata.                   |
| `corelayer.get_issue_summary` | Read | Fetch issue summary statistics for a group.                                      |
| `corelayer.list_integrations` | Read | List connected integration accounts for a group.                                 |
| `corelayer.search_org_memory` | Read | Search organization memory for historical context.                               |
| `corelayer.preflight`         | Read | Check a PR description against org memory; return failure modes to double-check. |

## Example Connector Workflows

Daily triage:

```text theme={null}
Use Corelayer to list open issues in our workspace. Summarize the top issues by
severity, last seen time, and event count. If any issue looks fixed based on
recent context, include it in a separate "needs human review" section.
```

Ticket creation:

```text theme={null}
Find high and critical Corelayer issues from the selected group. For each issue
that does not already have a ticket, draft a concise ticket with the issue
title, root cause, affected service, and recommended next step.
```

Historical context:

```text theme={null}
Search Corelayer organization memory for prior decisions about the failing
integration, then list related open issues and summarize what changed since the
last incident.
```

Pre-PR review:

```text theme={null}
Before I open this PR, check it against Corelayer with the preflight tool and
list any failure modes the org has hit before for a change like this.
```

## Local MCP

Use local MCP when your AI coding agent runs MCP servers as local stdio
processes. The local server is distributed as an npm package:

```bash theme={null}
npx -y @corelayer-ai/mcp
```

Your MCP host launches this command and communicates with it over standard input
and standard output.

Add Corelayer to your local MCP-compatible coding agent configuration:

```json theme={null}
{
  "mcpServers": {
    "corelayer": {
      "command": "npx",
      "args": ["-y", "@corelayer-ai/mcp"],
      "env": {
        "CORELAYER_API_KEY": "cl_key_...",
        "CORELAYER_API_URL": "https://api.corelayer.com"
      }
    }
  }
}
```

Restart your agent or editor after changing the MCP config.

## Local Authentication

The local MCP server resolves credentials in this order:

1. `CORELAYER_API_KEY`
2. the local CLI token from `~/.corelayer/config.json`

Prefer `CORELAYER_API_KEY` because it is explicit, revocable, and easier to
audit.

## Optional Local Default Group

If your local agent usually works in one Corelayer group, set
`CORELAYER_DEFAULT_GROUP` so group-scoped tools can omit `groupId`:

```json theme={null}
{
  "mcpServers": {
    "corelayer": {
      "command": "npx",
      "args": ["-y", "@corelayer-ai/mcp"],
      "env": {
        "CORELAYER_API_KEY": "cl_key_...",
        "CORELAYER_API_URL": "https://api.corelayer.com",
        "CORELAYER_DEFAULT_GROUP": "group-id"
      }
    }
  }
}
```

For remote MCP, use the `corelayer.list_groups` discovery flow instead of a
process-level default group.

## Additional Local Tools

The local MCP package also exposes write tools for authenticated local agents:

| Tool                          | Type  | Description                                 |
| ----------------------------- | ----- | ------------------------------------------- |
| `corelayer.close_issue`       | Write | Close one issue, optionally with feedback.  |
| `corelayer.reopen_issue`      | Write | Reopen one issue, optionally with feedback. |
| `corelayer.bulk_close_issues` | Write | Close multiple explicitly selected issues.  |

`corelayer.bulk_close_issues` requires explicit issue IDs, caps requests at 500
IDs, and never uses a select-all mutation.

## Environment Variables

| Variable                  | Description                                     | Default                     |
| ------------------------- | ----------------------------------------------- | --------------------------- |
| `CORELAYER_API_KEY`       | Corelayer API key or token.                     | CLI config fallback         |
| `CORELAYER_API_URL`       | Corelayer API base URL.                         | `https://api.corelayer.com` |
| `CORELAYER_DEFAULT_GROUP` | Optional local group ID for group-scoped tools. | —                           |
| `CORELAYER_TIMEOUT_MS`    | Corelayer API request timeout in milliseconds.  | `30000`                     |

## Verify Local Package

Check that npm can see the package:

```bash theme={null}
npm view @corelayer-ai/mcp version
```

You can also start the local server manually:

```bash theme={null}
CORELAYER_API_KEY=cl_key_... npx -y @corelayer-ai/mcp
```

The command starts a stdio MCP server and waits for MCP JSON-RPC messages. In a
terminal it may look idle; that is expected. Your MCP host is responsible for
sending requests.

## Troubleshooting

| Symptom                                   | Fix                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| The remote connector cannot authenticate. | Confirm it sends `Authorization: Bearer <key>` to the MCP endpoint.       |
| The connector cannot find a group.        | Call `corelayer.list_groups` first and choose the matching group by name. |
| Group-scoped tools ask for `groupId`.     | Use the group ID returned by `corelayer.list_groups`.                     |
| The local server exits immediately.       | Confirm Node.js 18+ is installed and `npx -y @corelayer-ai/mcp` runs.     |
| Local tools fail with missing auth.       | Set `CORELAYER_API_KEY` or run `corelayer login` locally.                 |
| The terminal appears to hang.             | This is normal; stdio MCP servers wait for JSON-RPC input from the host.  |