connection_status — check stored connection readiness

publ Reference
[Migration map](../reference/tool-name-migration.md).

# connection_status — check stored connection readiness

Use this to check whether the configured runtime can read its stored publ connection. It performs neither login nor sign-up and accepts no password, token, account ID, or channel selector.

## Input

Pass an empty object:

```json
{}
```

## Processing and result

The stdio HTTP adapter reads the configured credential file, validates its structure and owner-only permissions, and compares a stored `apiOrigin` with the selected API origin when that field is present. Legacy files without `apiOrigin` skip that comparison. This check itself sends no authentication request to publ.

A successful payload contains:

| Field | Value or meaning |
| --- | --- |
| `status` | `success`. |
| `code` | `CREDENTIALS_PRESENT`. |
| `environment` | Adapter label: `configured-server` for the HTTP adapter, or `demo-no-publ-requests` for demo. |
| `verification.confirmed` | `false`: no live authentication was established by this call. |
| `note` | Explains that the next read must confirm server access. |

Non-demo calls can also include the runtime `connection.environment` and `connection.apiOrigin`; those describe configuration, not successful authentication. Passwords, tokens, and the internal connection ID are not returned. See [result metadata](../reference/results.md#environment-and-links).

`CREDENTIALS_PRESENT` does not prove token freshness, access to every channel, or permission to perform a write. Use [channels_list](publ_channels_list.md) and [channel_context_get](publ_channel_context_get.md) to check the intended target through real reads. On hosted connections these belong to separate account and selected-channel resources; call only the read available in the current resource. Follow the business tool's permission and revision requirements even if those reads succeed.

## Inputs

This tool takes no input fields.

## Errors and next action

| Code | Meaning and response |
| --- | --- |
| `AUTH_REQUIRED` | No usable credential file, unreadable/invalid stored data, or another supported authentication requirement. A human/operator must repair the connection; do not assume a wrong password. |
| `CREDENTIAL_PERMISSIONS` | The file is not a regular private file or is accessible to other users. The operator must fix storage permissions. |
| `CREDENTIAL_ENVIRONMENT_MISMATCH` | Stored origin and selected origin differ. Use the connection belonging to the selected environment. |
| `INTERNAL_ERROR` | An unexpected failure needs diagnosis; no successful authentication should be inferred. |

Authentication requirements use application `status:action_required`; the other listed failures use `status:error`. Optional result fields can be absent on failure.

Hosted users follow the configured [connection guide](../hosted-mcp-console/connection-guide.md); a configured production login service must actually exist. Do not invent its URL or collect credentials through conversation. Sign-up takes place on the supported publ website and does not automatically authorize an MCP client.

## Effects and retry

The check does not log in, log out, refresh tokens, or mutate publ data. It may be repeated after the connection is repaired. A newly created connection can have a different internal identity; existing jobs cannot be adopted by manually changing their connection or task data.

Implementation: `src/server.ts`, `src/publ-http.ts::connectionId`, and the configured port implementation.