Skip to content
Canopy

The live catalog is read now and kept with the connection; session start checks the server against it. A put under an existing name replaces the connection with the catalog as it is now. A credential, if given, must be a secret the tenant holds and is sent as a bearer. Given none, a server that demands one is linked through an authorization: the answer carries the URL the owner opens, and the callback finishes the link. A server whose earlier authorization still opens is relinked with it.

PUT
/connections/{id}
curl --request PUT \
  --url https://api.canopyhq.dev/connections/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "credential": "example", "endpoint": "example", "name": "example", "result_limit": "example", "return_to": "example", "timeout": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The name the tenant gives the connection; installs select its tools by this.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

What the tenant supplies to link a server. The catalog is discovered here, never supplied. A server that demands a bearer and is given none is linked through an authorization; return_to is where the browser is sent once that is done.

object
credential
One of:
null
endpoint
required
string
name
required
string
result_limit
One of:
null
return_to
string | null
timeout
One of:
null
Examplegenerated
{
  "credential": "example",
  "endpoint": "example",
  "name": "example",
  "result_limit": "example",
  "return_to": "example",
  "timeout": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The outcome is replaced or unchanged, with the catalog just captured.

Media typeapplication/json

What a link answers: the connection as it stands, and, when the server demands an authorization, the URL the owner opens to grant it.

object
authorize
string | null
connection
required
object
auth
One of:
null
catalog
required
object
key
additional properties

A tool as advertised by its MCP server. An absent output schema stays absent.

object
description
required
string
input_schema
required
output_schema
One of:
null
endpoint
required
string
name
required

The tenant’s readable namespace for this connection’s tools.

string
result_limit
One of:
null
state

Where a connection stands: linked with its catalog, or waiting on the owner to authorize it. A linked connection whose token set was refused and could not be refreshed reads as needing authorization again.

string
Allowed values: linked authorizing needs_authorization
timeout
string | null
outcome
required

The result of applying a resource write at the door.

string
Allowed values: created replaced unchanged
Example
{
  "connection": {
    "auth": {
      "kind": "bearer"
    },
    "state": "linked"
  },
  "outcome": "created"
}

201

Section titled “201”

The connection, linked, with the catalog just captured.

Media typeapplication/json

What a link answers: the connection as it stands, and, when the server demands an authorization, the URL the owner opens to grant it.

object
authorize
string | null
connection
required
object
auth
One of:
null
catalog
required
object
key
additional properties

A tool as advertised by its MCP server. An absent output schema stays absent.

object
description
required
string
input_schema
required
output_schema
One of:
null
endpoint
required
string
name
required

The tenant’s readable namespace for this connection’s tools.

string
result_limit
One of:
null
state

Where a connection stands: linked with its catalog, or waiting on the owner to authorize it. A linked connection whose token set was refused and could not be refreshed reads as needing authorization again.

string
Allowed values: linked authorizing needs_authorization
timeout
string | null
outcome
required

The result of applying a resource write at the door.

string
Allowed values: created replaced unchanged
Example
{
  "connection": {
    "auth": {
      "kind": "bearer"
    },
    "state": "linked"
  },
  "outcome": "created"
}

202

Section titled “202”

The server demands an authorization: the connection stands as authorizing and authorize is the URL the owner opens. Starting authorization reports created or replaced, never unchanged.

Media typeapplication/json

What a link answers: the connection as it stands, and, when the server demands an authorization, the URL the owner opens to grant it.

object
authorize
string | null
connection
required
object
auth
One of:
null
catalog
required
object
key
additional properties

A tool as advertised by its MCP server. An absent output schema stays absent.

object
description
required
string
input_schema
required
output_schema
One of:
null
endpoint
required
string
name
required

The tenant’s readable namespace for this connection’s tools.

string
result_limit
One of:
null
state

Where a connection stands: linked with its catalog, or waiting on the owner to authorize it. A linked connection whose token set was refused and could not be refreshed reads as needing authorization again.

string
Allowed values: linked authorizing needs_authorization
timeout
string | null
outcome
required

The result of applying a resource write at the door.

string
Allowed values: created replaced unchanged
Example
{
  "connection": {
    "auth": {
      "kind": "bearer"
    },
    "state": "linked"
  },
  "outcome": "created"
}

400

Section titled “400”

An invalid body returns an error naming the field and reason; the name may be empty or the credential may name a secret the tenant does not hold.

401

Section titled “401”

No console token, or one that did not verify.

403

Section titled “403”

Only an owner of the tenant may configure it.

502

Section titled “502”

The server could not be reached, registered with, or read; nothing changed.