# Connect to publ MCP
Sign in with your existing publ account. If you need an account, follow the signup notice to publ.biz, complete registration there, then return to sign in.
## One connection address
Copy the server URL or connection sentence from the dashboard. New connections use one URL:
```text
https://mcp.publ.biz/mcp
```
The URL covers the account and the channels you explicitly authorize. The dashboard does not select an active business channel. Each operation supplies its own target, so concurrent clients cannot change each other's channel selection.
The server always generates links from `PUBL_PUBLIC_ORIGIN`. Configure the origin without `/mcp`, and copy the complete `/mcp` URL shown on the dashboard.
The original business-console shortcut is separate from that MCP origin. The
local DEV runner selects `https://console.dev.publ.biz`. Other hosts can explicitly
select `PUBL_CONSOLE_ENVIRONMENT=dev` or `prod`; without an explicit choice, an
exact registered API profile selects its corresponding console. Absent/custom
API profiles retain the production-console default. Conflicting registered
API/console profiles are rejected. This chooses a centrally registered address
and does not change the API origin or grant access.
| Address on the configured origin | Purpose |
|---|---|
| `/` | Human entry, leading to login or the dashboard |
| `/dashboard` | Connection URL and instructions |
| `/authorizations` | Approved-client identity, current scope, access reduction and revocation |
| `/reference` | English Markdown documentation |
| `/mcp` | The single Streamable HTTP resource for both MCP clients and CLI wrappers |
| `/.well-known/oauth-protected-resource/mcp` | Resource metadata advertised by the MCP bearer challenge |
| `/.well-known/oauth-protected-resource` | Discovery fallback describing that same `/mcp` resource |
| `/.well-known/oauth-authorization-server` | OAuth issuer and endpoint metadata |
| `/oauth/authorize`, `/oauth/token`, `/oauth/revoke` | Same-origin authorization, token rotation and revocation |
There are no per-operation URLs such as `/mcp/discover`, `/mcp/execute` or `/cli/members_list`. Send standard MCP `tools/call` requests to `/mcp`, naming `discover` or `execute` in the request. A business operation such as `members_list` is an argument to `execute`, with an explicit account/channel target. A trailing slash is not a second token audience: use the exact `/mcp` URL; invalid paths return a JSON error with the canonical address and never redirect bearer requests.
## Read-only connection
For an agent that should only look at your data, connect to `https://<server>/mcp/read` instead of `/mcp`. A read-only
connection can use only operations that read. Operations that change or send data are not listed. If one is called
anyway, it answers `ACCESS_LEVEL_READ_ONLY` and nothing is sent. The approval page for this address shows read only, with
the same account and channel choices as `/mcp`.
The `/mcp` approval page also offers the access level: full (the default) or read only. A connection keeps its level when
its tokens refresh; to change the level, connect again and approve. The access management page shows each connection's
level. A token from `/mcp/read` works only on `/mcp/read`, and a token from `/mcp` works only on `/mcp`.
The dashboard shows each connection mode as a card: full connection (`/mcp`) and read-only connection (`/mcp/read`).
Open a card to copy its server URL and its own prompt for your AI tool. Give the read-only address to agents with
limited permissions.
## Connect your client
1. Paste the dashboard's connection sentence into your AI tool, or add its exact URL in the tool's remote MCP settings using Streamable HTTP and OAuth. Use `publ` as the connection name; the product display name is **publ MCP**.
2. Open the client's authorization link. Sign in with publ if requested, then select account access and/or the channels this client may use. Permissions start unchecked.
3. Approve access and return to the client. Its tool list contains `discover` and `execute`.
Copying a URL does not authorize a client or establish a working connection. Support for prompt-driven setup varies by client and version. OAuth is provided by this MCP service using the existing publ login; publ does not need its own OAuth service. A valid session here skips password entry. A session in the separate business console is not automatically shared.
Never paste a publ password, browser cookie, access token or refresh token into an AI conversation. The client receives MCP tokens, not your publ API credentials. Compatible clients rotate their MCP refresh tokens automatically.
The canonical `/mcp` resource and authorization-server metadata advertise only `publ:mcp`. Clients may use that discovered scope without an explicit override. Account and channel selection occurs on the consent screen; adding legacy `publ:account` or `publ:channel` scopes does not grant more access and is rejected for `/mcp`.
For local verification, use the same configured HTTPS origin for login, OAuth, the dashboard and System Admin. Browser cookies are shared between ports on the same hostname, while separate local databases do not share sessions. A valid session on one port is not evidence of a valid session on another. Use one integrated server, or distinct hostnames with separately trusted certificates for intentionally isolated test environments.
## Find and execute an operation
The server keeps the business operations internally rather than sending hundreds of definitions on connection. `discover` has three modes:
- `targets`: list the approved account/channel targets, with an optional query and pagination.
- `search`: provide an explicit target and **at least one nonblank keyword** in `query`. Separate multiple keywords with spaces. Search operation names, available display titles and English descriptions. Any partial keyword match qualifies, even when other keywords do not match. Exact operation names rank first, followed by more matched keywords, stronger name/title matches, and operation name as a stable tie-breaker. Results are short summaries, at most ten per page (five by default), with `nextOffset` when more exist.
- `describe`: read one operation's full description, input/output schemas and annotations. Supply its exact name from search.
Clients translate the user's request, in any language, into short English keywords that name the operation and its object (for example `ott episode list`, `member list`, `sales statistics`), with no sentences and no particles; the server instructions, the `discover` description and the `query` field say so, and a search with no result answers a `hint` to retry that way. Search ignores case, normalizes character width, and keeps a finite set of earlier aliases, such as `customer` / `member` / `고객` / `회원` and `directory` / `list` / `명단` / `목록`. For example, `고객 명단` can find `members_list`; `memb unknownword` still returns member-related matches. Aliases search only the existing, authorized catalog and never add operations or permissions. This is lexical matching, not unrestricted semantic similarity or typo correction. If a concept has no matching alias, use its English keyword or a shorter part of its operation name. Unknown terms return no results. Empty or whitespace-only searches return `QUERY_REQUIRED` with keyword instructions; `targets` and `describe` do not require keywords.
Display titles appear when the business tool provides them. The stable operation name remains the identifier passed to `describe` and `execute`.
For example, find a channel read operation:
```json
{"mode":"search","target":{"kind":"channel","channelCode":"YOUR_CHANNEL"},"query":"channel_context"}
```
Then describe `channel_context_get` and call `execute`:
```json
{"target":{"kind":"channel","channelCode":"YOUR_CHANNEL"},"operation":"channel_context_get","arguments":{"channelCode":"YOUR_CHANNEL"}}
```
Business tool names in the Reference are the values of `execute.operation`. They are not additional tools registered on the unified connection. All input validation, current publ permissions, revision checks, write confirmations and recovery rules still apply. `execute` has conservative mutation/destruction annotations because it can perform both reads and writes; consult the selected operation's annotations and obtain authorization for the actual action.
For account operations use `target: {"kind":"account"}`. A channel operation's `arguments.channelCode` must match `target.channelCode`. Changing either value cannot grant access. Newly created or newly entitled channels are not added to an existing approval automatically: authorize a new connection with the desired selection.
On the approval page, **All channels (n)** approves every channel you can manage at that moment; you can also choose channels one by one. All channels covers only the channels you have now: a channel created later needs a new approval.
When a change returns a task ID, preserve its task type, original request ID and target. Task state is isolated by client grant and target. An uncertain response is not proof of success; use `execute` with the permitted status/resume operation on the same target. Never repeat uncertain creation with a new request ID.
## CLI access
A CLI uses the same `/mcp` HTTP protocol and calls the same two tools; it does not need a local stdio MCP server or duplicate business logic. The repository includes `scripts/mcp-http-probe.mjs` to verify this path with an already-issued MCP token. The local integration suite exercises a separate CLI process against the unified endpoint.
This probe is not a published installer or a complete CLI OAuth-login product. A downloadable distribution and its interactive login workflow remain separate work. MCP clients do not need to download a CLI to use discovery and execution.
## Existing connections
The earlier `/mcp/account` and `/mcp/channels/{channelCode}` resources remain compatibility endpoints for existing scoped connections. They retain their original tool lists and audience restrictions. Their tokens cannot access `/mcp`; unified tokens cannot access the older resources. New dashboard instructions use only `/mcp`.
Authorize a new unified connection to migrate.
## Access management and console shortcut
Authorized clients, the second sidebar item, shows each client's approved account/channel access. Revoke an individual client there, or disconnect the current publ login to remove its stored publ tokens and MCP grants. Signing out only ends the browser session.
Open publ console takes you to the existing business console. It does not automatically sign you in there or execute a business operation.
The UI follows your browser language: English (fallback), Korean, Japanese, Traditional Chinese, Simplified Chinese or Spanish. Reference prose and protocol descriptions remain English. Actual user content retains its original language.
See [authentication and deployment requirements](authentication.md) for token lifetimes and current integration limits.
## Identify and reduce an existing authorization
An older connected server may omit this metadata or management form. See the [response fields and limits](../reference/unified-hosted.md#connection-identity-and-reduced-access).
Call `discover` with `{"mode":"targets"}` on the unified MCP endpoint. The
`connection.reference` is a non-secret connection ID, shared with the signed-in
**Authorized clients** page. Compare that ID, the saved authorization time and
the actual scope. A client-supplied name such as “Codex” does not distinguish a
desktop client from a CLI. A last-used time is not shown when none was recorded.
Open `connection.managementUrl` to view that exact authorization. The page still
requires the owning publ account's browser session. Its **Reduce access** form
can remove account/channel access, but cannot add anything beyond the current
scope. Keep at least one permission or revoke the connection entirely. A stale
form must be reloaded. Other authorizations keep their own access and expiry.
Existing access tokens use the persisted reduced scope on their next request;
refresh does not restore removed access or extend the grant's existing lifetime.
Requests still waiting for their authorization check reject the old scope.
Operations already dispatched to publ cannot be undone by changing access.
Retain task IDs and inspect outcomes before retrying writes. A new context keeps
the same grant's durable jobs for retained targets; removed targets are blocked.
Opening the browser, logging in, or viewing this management page does **not**
reauthenticate an MCP client. To request additional permissions, use that client's
supported reconnect/reauthentication flow and approve its new consent. Do not
construct an authorization URL manually or copy tokens between clients.
