CatalogService

Read what exists: the apps atmon can reach, the tools each one brings, and one tool's full definition. Most callers reach this through search rather than by browsing, and use it to draw their own connect screen.

Every call is a POST to https://api.atmon.ai/automaton.v1.CatalogService/<Call> with a JSON body, and authenticates with Authorization: Bearer <your project key>. Field names in JSON are lowerCamelCase, so the field written tool_slug below is toolSlug on the wire. How to call the API has the whole convention.

Calls

ListToolkits

Lists the toolkits the caller can see: the shared catalog, plus the caller's own private toolkits when a project is named.

Request ListToolkitsRequest, response ListToolkitsResponse.

POST /automaton.v1.CatalogService/ListToolkits HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "projectId": "..."
}

The response:

{
  "toolkits": [{
    "slug": "...",
    "name": "...",
    "description": "...",
    "version": "...",
    "authSchemes": ["..."],
    "ownerProjectId": "...",
    "category": "...",
    "connectable": true,
    "connectability": "TOOLKIT_CONNECTABILITY_READY"
  }]
}

GetToolkit

Reads one toolkit by slug. A project-owned entry wins over a shared entry with the same slug.

Request GetToolkitRequest, response GetToolkitResponse.

POST /automaton.v1.CatalogService/GetToolkit HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "slug": "...",
  "projectId": "..."
}

The response:

{
  "toolkit": {
    "slug": "...",
    "name": "...",
    "description": "...",
    "version": "...",
    "authSchemes": ["..."],
    "ownerProjectId": "...",
    "category": "...",
    "connectable": true,
    "connectability": "TOOLKIT_CONNECTABILITY_READY"
  }
}

ListTools

Lists tools, optionally narrowed to one toolkit or one kind. An agent should resolve an intent through the router rather than enumerate this.

Request ListToolsRequest, response ListToolsResponse.

POST /automaton.v1.CatalogService/ListTools HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "toolkitSlug": "...",
  "kind": "TOOL_KIND_ACTION",
  "projectId": "..."
}

The response:

{
  "tools": [{
    "slug": "...",
    "toolkitSlug": "...",
    "kind": "TOOL_KIND_ACTION",
    "description": "...",
    "inputSchemaJson": "{}",
    "outputSchemaJson": "{}",
    "requiredScopes": ["..."],
    "ownerProjectId": "...",
    "accessClass": "..."
  }]
}

GetTool

Reads one tool's full definition by its catalog-wide slug: description, both JSON Schemas, required scopes, and access class. This is what the MCP describe_tool meta-tool answers with.

Request GetToolRequest, response GetToolResponse.

POST /automaton.v1.CatalogService/GetTool HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "slug": "...",
  "projectId": "..."
}

The response:

{
  "tool": {
    "slug": "...",
    "toolkitSlug": "...",
    "kind": "TOOL_KIND_ACTION",
    "description": "...",
    "inputSchemaJson": "{}",
    "outputSchemaJson": "{}",
    "requiredScopes": ["..."],
    "ownerProjectId": "...",
    "accessClass": "..."
  }
}

GetToolkitConnectSpec

Reads what a connect form for one toolkit needs: the templated base URL, the account variables the address is built from, and the schemes a connection can be made under. It carries no credential and no endpoint a credential is presented to.

Request GetToolkitConnectSpecRequest, response GetToolkitConnectSpecResponse.

POST /automaton.v1.CatalogService/GetToolkitConnectSpec HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "slug": "...",
  "projectId": "..."
}

The response:

{
  "spec": {
    "toolkitSlug": "...",
    "baseUrlTemplate": "...",
    "accountVariables": [{ ... }],
    "authSchemes": [{ ... }]
  }
}

Messages

AccountVariableSpec

AccountVariableSpec is one entry of a toolkit's account_variables: a fact about the customer's own deployment that the connection captures and the base URL renders. Description is the sentence the connecting person is asked for it with, and Example is a well-formed answer.

GetToolRequest

GetToolResponse

GetToolkitConnectSpecRequest

GetToolkitConnectSpecResponse

GetToolkitRequest

GetToolkitResponse

ListToolkitsRequest

ListToolkitsResponse

ListToolsRequest

ListToolsResponse

Tool

Toolkit

ToolkitAuthSchemeSpec

ToolkitAuthSchemeSpec is one scheme a connection to the toolkit can be made under, with the fields that scheme's form needs. The type-specific fields are empty for the types they do not apply to.

ToolkitConnectSpec

ToolkitConnectSpec is what a connect form for one toolkit is built from: where its calls go, the per-customer values the address is built from, and the schemes a connection can be made under.

The scheme list is narrower than Toolkit.auth_schemes, which reports every scheme the toolkit declares. A client_credentials scheme is absent here because no connected account is made under it: the project holds that credential and InitiateConnection refuses the scheme by name.

Enums

ToolKind

ToolkitConnectability

ToolkitConnectability says what stands between a toolkit and a connected account on this deployment. It is deployment state, not catalog data: the same toolkit definition answers differently on a node whose operator has registered its OAuth app and on a node that has not.