# MCP Server Reference

Topline uses Model Context Protocol (MCP) at several trust boundaries. These
servers share a protocol, but they do not share identity, lifetime, or tool
authority. Choose the narrowest server that matches the task.

## Server inventory

| Server | Primary client | Transport and route | Identity | Purpose |
| --- | --- | --- | --- | --- |
| Topline Build MCP | External Codex or Claude Code | Local stdio package plus Streamable HTTP at `/mcp/build` | OAuth PKCE or connector token | Build and operate artifact-app drafts without sending the app directory through model tokens. |
| Topline Workspace MCP | External MCP clients | Streamable HTTP at `/mcp/workspace` | OAuth PKCE or connector token | Read accessible conversations, documentation, approved preferences, permission-filtered context, glossary terms, and reviewed company knowledge. |
| Legacy Harness MCP | Existing external MCP clients | Streamable HTTP at `/mcp/harness` | OAuth PKCE or connector token | Compatibility union of Build and Workspace tools; do not use for new setup. |
| Platform Workforce Bridge | One Topline coding task | Streamable HTTP at `/api/workforce/bridge/mcp` | Short-lived workforce task token | Gives a coding agent only the tools and records attached to its task. |
| Storybook MCP | UI coding tasks | Streamable HTTP at `/api/design-systems/storybook/mcp` | Signed-in session or task token | Inspect tenant Storybook stories, props, and rendered component guidance. |
| AgentCore Harness Bridge | Managed AgentCore runtime | Streamable HTTP at `/api/agentcore/harness/mcp` | Managed runtime/task context | Exposes the appropriate harness tools to AgentCore execution. |
| Customer MCP Broker | Managed chat and Topline coding tasks | Streamable HTTP at `/api/mcp/connections/:id/proxy` | Short-lived chat or workforce token | Safely exposes an operator-approved subset of a tenant's remote MCP server tools. |

Do not copy a credential or configuration from one server into another. A
workforce task token is not a general Topline API token, and a browser session
cookie is not a portable MCP credential.

## Customer MCP connections

Operators with Developer Access permissions can register future remote MCP
servers without a vendor-specific Topline integration. Each connection stores
the tenant, public HTTPS endpoint, workflow surfaces, discovered tool manifest,
and explicit tool allowlist. Connections may use no authentication, a bearer
credential referenced from the tenant credential library, or browser-approved
MCP OAuth. Secrets are resolved only inside the server-side broker.

Connection checks reject local/private destinations and redirects. Discovery
does not grant every advertised tool: all newly discovered tools remain blocked
until an operator classifies and explicitly enables them. Server annotations
are displayed as untrusted hints. The broker rechecks tenant, task/conversation, connection
status, workflow surface, and allowed tool name on every MCP request.

Supported in this release:

- public HTTPS Streamable HTTP MCP endpoints;
- no authentication, credential-library bearer authentication, or MCP OAuth;
- MCP `2026-07-28` stateless protocol with automatic 2025-era fallback;
- managed chat harness and coding-task attachment; and
- connection, discovery, tool-policy, status, and disconnect controls.

Not supported by this path: arbitrary stdio commands, private-network targets,
or custom caller-supplied headers. Those require a separate reviewed
transport/auth implementation rather than storing raw config inside an agent
runtime.

## Topline Build MCP

The `@topline-build/harness-mcp` package runs locally in an external coding
harness. Its main advantage is filesystem locality: it can read an artifact
app directory, validate its manifest, and create a compressed upload without
placing the source bundle into a model prompt.

### Setup

1. Open **Account > Developer Access** in Topline.
2. Choose the setup instructions for Codex or Claude Code.
3. Copy the **Build artifacts** configuration.
4. Complete browser-based OAuth approval when prompted.
5. Add `artifact-app.json` to the application directory.
6. Ask the coding harness to deploy the draft with the MCP tool.

The current server version is `0.5.0`; the current protocol version is `2025-11-25`.

### Tools

| Tool | Purpose |
| --- | --- |
| `platform_inspect_artifact_app` | Check local paths and package boundaries without authentication, upload, or remote draft creation. Pass its bundle hash to deploy as `expectedBundleSha256`; full manifest validation remains server-side. |
| `platform_deploy_artifact_app` | Validate the manifest, package the app directory, upload the bundle, and start or report draft deployment. |
| `platform_artifact_status` | Return recent deployment state for an artifact app. |
| `platform_validate_artifact` | Return bounded trusted smoke and rendered-page health evidence without requiring a browser session. |
| `platform_read_artifact_logs` | Return bounded and redacted deployment logs. |
| `platform_open_artifact` | Return Topline UI, draft, version, source, schedule, and promotion handoff URLs. |
| `platform_connection_check` | Complete the one-time Build challenge shown in Developer Access. |
| `platform_delete_artifact_draft` | Permanently remove a same-connection, private, unpromoted draft after exact-id confirmation. |

### Deliberate limits

- Live promotion remains an operator action in the Topline artifact UI.
- Uploads must be `tar.gz` bundles.
- Symlinks, absolute paths, parent traversal, `.env*`, `.git`,
  `node_modules`, build caches, and oversized bundles are rejected.
- Direct source queries and schedule mutation are not part of Hosting MCP v1.
- The MCP package does not mint or store unrelated cloud credentials.

## Topline Workspace MCP

Topline Workspace MCP is the customer-facing context server at
`/mcp/workspace`. Its tool families are accessible conversation search/read,
documentation search/read, approved preferences, permission-filtered memory and company context, glossary lookup,
and capability-gated glossary and company-knowledge changes. Direct writes require an
explicit operator request and glossary steward authority; ordinary model
discoveries remain proposals.

`list_workspaces` returns a bounded, cursor-paginated catalog of workspaces the
operator can access in the active tenant. Conversation tools require
`chat:read`, enforce tenant plus owner/share/scope
visibility, and return only bounded user-visible message text. Reads paginate
older pages with `nextBeforeMessageId`, identify the owning workspace, and mark
individual messages truncated at 4,000 characters. Transcript search scans
bounded 100-message windows and exposes a cursor when older history remains.
Conversation discovery also returns `nextCursor` so clients can continue past
the first bounded result page.

Topline Build MCP is the artifact server at `/mcp/build`. Its hosted tools
cover private artifact creation/status/logs/handoffs, Storybook configuration,
and local Bedrock token-command guidance. Local directory packaging and deploy
stay in `@topline-build/harness-mcp`; the hosted server does not advertise that
local-only tool. The generated **Harness MCP Tool Reference** is the
authoritative tool/schema inventory for both products.

Each endpoint advertises its own OAuth protected-resource metadata and accepts
OAuth access tokens issued for that exact resource or manual connector tokens.
`tools/list` filters by product and token scopes;
preference and glossary tools also require the operator capabilities documented
in the generated reference. Resource handlers continue to enforce tenant,
actor, and artifact ownership.

`/mcp/harness` remains a deprecated compatibility union. It does not expose the
product-bound verification tool. New integrations should choose Build,
Workspace, or both so clients receive smaller, clearer tool catalogs. The
legacy route advertises successor links; no sunset date has been scheduled.

## Connection verification and authorization management

Developer Access distinguishes authorization from verified connectivity. An
OAuth grant proves consent; a successful ordinary call records current client
activity. **Verify connection** adds a stronger check:

1. Topline creates a product-bound one-time code that expires in ten minutes
   and stores only its SHA-256 hash.
2. The operator copies the check instruction into the intended MCP client.
3. That client calls `platform_connection_check` on `/mcp/build` or
   `/mcp/workspace` with the code.
4. Developer Access reads the owner-scoped result and identifies the auth kind
   and client that completed it.

Active OAuth grants are listed per product with scopes, last use, success and
failure state, and call counts. Revocation requires an explicit confirmation
and affects only the selected grant. Reconnect by running the product setup in
the client and approving OAuth again.

## Platform Workforce Bridge

Every coding task receives a generated `.cursor/mcp.json` that points to the
task-scoped workforce bridge. The bridge creates a fresh MCP server instance
per HTTP request and resolves the task from its signed token.

The bridge is not a general repository backdoor. Tool families provide bounded
operations for:

- reading task instructions and current state;
- operator questions and confirmations;
- artifact draft creation, validation, deployment preparation, logs, and
  cleanup evidence;
- Storybook inspection and validation;
- source/data discovery through approved interfaces;
- schedules and automation handoffs;
- glossary reads and explicit steward-authorized create/update;
- task-scoped assets;
- browser actions that require operator approval;
- bounded Redis inspection where enabled; and
- task-owned workspace tables with documented schemas.

Tools are registered centrally and may be feature-flagged. For example,
`propose_browser_action` is registered only when brokered browser approvals are
enabled.

### Coding-agent lifecycle

A coding agent should use the bridge to:

1. read the task and relevant platform evidence;
2. ask for missing operator input instead of inventing it;
3. implement inside its assigned workspace;
4. run the smallest relevant checks;
5. report validation evidence and blockers; and
6. return control for operator review or promotion.

The bridge token expires with the task boundary. It must not be copied to
another workspace or reused for a different task.

## Storybook MCP

The Storybook MCP endpoint provides a live tenant design-system reference to
UI coding tasks. It exists so agents inspect current stories and component
guidance before changing the application instead of guessing from source.

The generated task MCP configuration can include both:

- `platform-workforce-bridge` for platform/task operations; and
- `storybook` for the published Storybook MCP endpoint.

Storybook access does not grant artifact deployment, source access, or general
workforce authority.

## AgentCore Harness Bridge

Managed AgentCore chat/runtime providers connect to an HTTP MCP bridge exposed
by the Topline server. This avoids giving the managed runtime direct database,
AWS control-plane, or repository access. The bridge resolves the allowed tools
for the current invocation and applies the same platform authority model used
by the rest of the harness.

## Authentication and authorization

MCP authentication proves who or what is calling. It does not replace tool
authorization.

Depending on the server, Topline uses:

- browser session identity;
- OAuth with PKCE;
- revocable connector tokens;
- scoped service authentication; or
- short-lived workforce task tokens.

After authentication, handlers enforce the applicable tenant, actor,
capability, task, artifact, source, conversation, or schedule boundary.
Sensitive values must be referenced through the approved secret system rather
than placed in MCP configuration, prompts, tool arguments, or logs.

## Tool discovery and invocation

Streamable HTTP clients send JSON-RPC requests to the configured MCP endpoint.
Tool discovery uses `tools/list`; execution uses `tools/call`. Clients should
send the configured MCP protocol version and support both JSON and event-stream
responses when required by the transport.

The Topline Build, Workspace, legacy Harness, and Customer MCP Broker endpoints accept both protocol eras. Modern
clients use `server/discover` and MCP `2026-07-28` per-request envelopes without
session IDs. Older clients continue to use the 2025 initialize flow. Outbound
customer connections and built-in HTTP manifest discovery prefer the modern
era, cache the discovery verdict per authorization context for ten minutes,
and fall back automatically when a server is legacy-only.

Do not assume a tool exists because it was present in a previous task. Tool
availability can vary by server, feature flag, capability, task type, and
runtime configuration. Discover tools for the active server and treat explicit
authorization or configuration errors as boundaries, not prompts to seek a
broader credential.

## Operator safety boundaries

- Do not expose raw database credentials through MCP.
- Do not place customer rows, cookies, tokens, typed browser values, or raw PII
  into logs or tool responses.
- Prefer bounded, redacted inspection tools over general shell or database
  access.
- Keep live artifact promotion and other consequential production actions
  operator-controlled unless a separately reviewed tool explicitly supports
  them.
- Require confirmation for brokered browser actions and other configured
  operator-confirmation flows.
- Audit security-relevant token issuance, revocation, proposals, deployment
  handoffs, and tool calls.

## Troubleshooting

### The client cannot discover tools

1. Confirm the configured URL and transport match the intended server.
2. Confirm the MCP protocol version.
3. Complete OAuth or refresh the intended scoped token.
4. Check whether the server is enabled for the current task type or intent.
5. Inspect the HTTP status before changing credentials: `401` is missing or
   invalid authentication, `403` is insufficient authority, and `404` often
   indicates the wrong server route.

### A tool is missing

- Verify the feature flag and capability required by that tool.
- Confirm the request is connected to the correct server.
- For coding tasks, verify that `.cursor/mcp.json` belongs to the current task.
- Refresh tool discovery after configuration changes; manifests can be cached
  for up to 60 seconds.

### A tool call is denied

Treat the denial as authoritative. Confirm tenant ownership, task attachment,
resource identity, and capability. Do not switch to a broader token merely to
bypass the failed authorization check.

### Deployment succeeds but live promotion is unavailable

That is expected for Hosting MCP v1. Open the returned promotion handoff in
Topline and complete operator review there.

## Documentation maintenance

When adding or changing an MCP server or tool family:

1. update this inventory and the server-specific setup guide;
2. document authentication, scopes, resource boundaries, and destructive
   capabilities;
3. include one successful workflow and common failure recovery;
4. keep tool names and routes aligned with the runtime registry;
5. add searchable terms operators will actually use; and
6. remove or label stale migration guidance so it is not mistaken for current
   behavior.