list_agent_mcp_attachments

GET

/v1/agents/{agent_id}/mcp-attachments

curl --request GET \
  --url https://app.everruns.com/api/v1/agents/example/mcp-attachments

• Production API

Lists the effective MCP attachments after capability, harness, and agent layers are merged. Connection state and permitted actions are resolved for the current caller.

Parameters

Path Parameters

agent_id

required

string

Agent ID (prefixed) or name

Responses

200

Effective MCP attachments for the agent

Media typeapplication/json

Array<object>

Effective MCP attachment projected for an agent and the current caller.

object

action

required

Connection action available to the current caller.

string

Allowed values: none connect authorize ask_admin

acts_as

required

Identity whose connection is used when the attachment calls the MCP server.

string

Allowed values: none service user

can_revoke

required

Whether the current caller can revoke the active connection.

boolean

connected_as

Connected account name, or the preset name when the provider did not supply one.

string | null

connection_provider

OAuth provider key used to create or revoke the attachment connection.

string | null

contributor

One of:

null

null

object

Capability that contributed the attachment, when the winning source is a capability.

object

href

required

UI path for the capability detail page.

string

id

required

Canonical capability ID.

string

name

required

Human-readable capability name.

string

editable

required

Whether the attachment is defined directly on the agent and can be removed there.

boolean

header_names

required

Header names configured for the endpoint; secret header values are omitted.

Array<string>

name

required

Logical attachment name used in the agent’s MCP configuration.

string

overridden_sources

required

Lower-precedence configuration layers overridden by this attachment.

Array<object>

Configuration layer that was overridden by the effective MCP attachment.

object

source

required

Overridden configuration layer.

string

Allowed values: capability harness agent

source_label

required

Human-readable name of the overridden capability, harness, or agent layer.

string

preset_id

ID of the active catalog preset when the reference resolves.

string | null

preset_name

Catalog preset name referenced by the attachment, including a missing preset.

string | null

source

required

Highest-precedence configuration layer that supplied this attachment.

string

Allowed values: capability harness agent

source_label

required

Human-readable name of the winning capability, harness, or agent layer.

string

state

required

Current preset and connection availability.

string

Allowed values: ready connection_missing preset_missing

tools

required

Cached names of tools exposed by the MCP server.

Array<string>

tools_available

required

Whether at least one cached tool name is available.

boolean

url

Effective MCP endpoint URL from the catalog preset or inline configuration.

string | null

Example

[
  {
    "action": "none",
    "acts_as": "none",
    "overridden_sources": [
      {
        "source": "capability"
      }
    ],
    "source": "capability",
    "state": "ready"
  }
]

404

Agent or harness not found

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

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

• Error recovery — ErrorResponse.allowed_actions carries rels 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 rels 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 documented in knowledge/execution/api-conventions.md 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. Closed vocabulary documented in knowledge/execution/api-conventions.md — 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

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

500

Internal server error

Media typeapplication/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

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

• Error recovery — ErrorResponse.allowed_actions carries rels 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 rels 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 documented in knowledge/execution/api-conventions.md 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. Closed vocabulary documented in knowledge/execution/api-conventions.md — 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

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}