# GET /v1/mcp-servers - List all MCP servers

Source: <https://everruns.com/docs/api/operations/list_mcp_servers/>

GET

/v1/mcp-servers

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/mcp-servers';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request GET \
  --url https://app.everruns.com/api/v1/mcp-servers
```

* Production APIapp.everruns.com/api/v1/mcp-servers

## Parameters

### Query Parameters

**search**

string | null

Search by name or description (case-insensitive substring match).

**include\_archived**

boolean | null

Include archived MCP servers. Deleted MCP servers never appear in lists.

## Responses

### 200

List of MCP servers

Media typeapplication/json

Response wrapper for list endpoints. All list endpoints return responses wrapped in a `data` field.

object

**data**

required

Array of items returned by the list operation.

Array

Wrapper that adds API and UI links to a serialized resource.

Uses `self_url` (not `url`) for the API link to avoid collision with resources that already have a `url` field (e.g. McpServer). The `allowed_actions` array carries state-aware hypermedia links — empty (and omitted from the wire shape) until the underlying resource opts into the convention by overriding `ResourceUrlable::allowed_actions`.

object

**api\_key\_set**

required

Whether an API key has been configured.

boolean

**archived\_at**

Timestamp when the MCP server was archived.

string | null format: date-time

**auth\_mode**

Authentication mode for this MCP server.

string

Allowed values: none api\_key oauth

**connection\_check**

One of:

* object

  Whether this OAuth preset’s sign-in service was reachable when it was last checked. Present only on OAuth presets.

  object

  **checked\_at**

  When the check ran; absent when it has not run.

  string | null format: date-time

  **host**

  Host of the request that failed, when the check failed.

  string | null

  **reason**

  Short, safe explanation of a failed check.

  string | null

  **status**

  required

  Check outcome.

  string

  Allowed values: ready blocked\_by\_network\_policy unreachable failed not\_checked

* null

  null

**created\_at**

required

Timestamp when the MCP server was created.

string format: date-time

**deleted\_at**

Timestamp when the MCP server was deleted.

string | null format: date-time

**description**

Human-readable description of the MCP server.

string | null

**elicitation\_policy**

Which elicitation modes this server may use (`url` by default).

string

Allowed values: url url\_and\_form none

**headers**

Additional HTTP headers for authentication. Keys are header names, values are header values.

object

***key***

additional properties

string

**id**

required

Unique identifier for the MCP server.

string

**name**

required

Display name of the MCP server.

string

**oauth\_provider\_id**

Stable provider id used for user-scoped OAuth connections.

string | null

**presentation**

One of:

* object

  Title, icon, and links published by the remote server. The operator `name` and `description` are unchanged.

  object

  **description**

  string | null

  **documentation\_url**

  string | null

  **fetched\_at**

  string | null format: date-time

  **icons**

  Array\<object>

  object

  **mime\_type**

  string | null

  **sizes**

  Array\<string>

  **src**

  required

  `https` URL on the MCP server’s origin, or a raster `data:` URI.

  string

  **theme**

  One of:

  * string

    string

    Allowed values: light dark

  * null

    null

  **sources**

  Which documents contributed. Not shown in the UI.

  Array\<string>

  **title**

  string | null

  **version**

  string | null

  **website\_url**

  string | null

* null

  string

  Allowed values: light dark

* string

  null

* null

  null

**protocol\_mode**

Protocol-era adoption policy for the MCP client (`auto` negotiates).

string

Allowed values: auto 2025-03-26 2025-06-18 2026-07-28

**service\_connection\_provider**

Connection provider whose connection on an agent’s service virtual user supplies the service credential instead of an MCP OAuth grant.

string | null

**status**

required

Current lifecycle status of the MCP server.

string

Allowed values: active disabled archived deleted

**transport\_type**

required

Transport type (currently only HTTP supported).

string

Allowed values: http stdio

**updated\_at**

required

Timestamp when the MCP server was last updated.

string format: date-time

**url**

required

URL of the MCP server endpoint.

string

**allowed\_actions**

State-aware hypermedia actions the caller can take on this resource next (e.g. `cancel`, `events`, `update`). Omitted from the wire shape when empty so resources that haven’t opted into the convention don’t grow their payloads.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed `rel` vocabulary distinguishes them.

object

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

Absolute (preferred) or relative URL the caller may invoke directly. **Always present on entity hypermedia actions** (`WithUrls<T>.allowed_actions`); **optional on error-recovery actions** (`ErrorResponse.allowed_actions`) where the matching `operation_id` is enough and the URI is implicit from the failed call.

string | null

**method**

HTTP method to use against `href`. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

OpenAPI `$ref` to the request-body schema, when the action takes one (e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

**self\_url**

required

Full API endpoint URL for this resource.

string

**ui\_link**

required

Alias for `view_url`, used by command and MCP outputs.

string

**view\_url**

required

Full UI URL for viewing this resource.

string

##### Example

```json
{
  "data": [
    {
      "auth_mode": "none",
      "connection_check": {
        "host": "mcp.linear.app",
        "status": "ready"
      },
      "description": "Atlassian MCP Server for Jira and Confluence",
      "elicitation_policy": "url",
      "id": "mcp_01933b5a00007000800000000000001",
      "name": "atlassian-mcp-server",
      "presentation": {
        "icons": [
          {
            "theme": "light"
          }
        ],
        "title": "GitHub MCP Server",
        "website_url": "https://github.com"
      },
      "protocol_mode": "auto",
      "service_connection_provider": "github",
      "status": "active",
      "transport_type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp",
      "allowed_actions": [
        {
          "method": "POST"
        }
      ]
    }
  ]
}
```

### 500

Internal server error