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/v1/bridge/mcp (legacy alias: /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.
Hosted MCP artifact	Managed chat and Topline coding tasks through the Customer MCP Broker	Exact live artifact route /_artifact/mcp	Platform-managed private bearer plus IAM-signed invocation	Runs a customer-built FastMCP tool server on Topline without bypassing Connected MCP server review.

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 customer-managed 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.

Hosted MCP artifacts

Customers can also ask a Topline coding task to build a server from the blessed fastmcp-server artifact template. External Build MCP can inspect and deploy a complete package but does not currently scaffold this template. The app-only kind: "mcp_server" contract exact-pins FastMCP 3.4.7, uses stateless JSON Streamable HTTP at /_artifact/mcp, and keeps the Lambda URL and bearer private. Only a validated promoted deployment can be connected.

The artifact does not self-connect or self-approve. A workspace MCP manager chooses Connect to Topline on the promoted live artifact; this opens Developer Access with that artifact selected. The manager reviews every tool and enables chat, coding, and agent assignments explicitly. Promotion or rollback moves the connection to a fail-closed recheck state and invalidates coding authority for the prior deployment.

See Build a hosted MCP server for customer use cases, the manifest contract, build and connection workflow, and current data and transport limits.

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 > Assistant > Developer Access > Connect an AI assistant.
2. Choose Codex or Claude Code and expand Topline Build MCP.
3. Copy the Codex configuration, or review View setup message and choose Open in Claude Code or Copy message. Claude Code opens a prefilled prompt and asks for the project folder and installation scope.
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.

Codex and Claude Code can also download private, account-specific plugin bundles from the same Developer Access product cards. Plugins combine the native MCP connection with starter workflows; manual setup remains available. See Native assistant plugin pilot for installation, reconnect behavior, and client acceptance checks.

The current server version is 0.7.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. It is also the control surface for users who work primarily through an MCP client. Its tool families include workspace lifecycle, accessible conversation search/read, documentation search/read, approved preferences, permission-filtered memory and company context, glossary lookup, explicitly enabled customer-profile reads, and capability-gated glossary and company-knowledge changes. Direct writes require an explicit operator request and the corresponding OAuth scope; ordinary model discoveries remain proposals.

list_workspaces returns a bounded, cursor-paginated catalog of workspaces the operator can access in the active tenant, including whether each workspace is writable. create_workspace and update_workspace require workspace:write and reuse the app's default-skill, ownership, co-author, audit, and live-update behavior. Workspace deletion has its own workspace:delete scope and requires plan_workspace_delete followed by delete_workspace with the same workspace id and a fresh state-bound plan token. Only the owner can delete; deletion unfiles retained conversations, todos, and artifacts and removes workspace-only shares, bindings, and maintenance documents.

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.

MCP-only workspace parity

Parity is defined by workspace capability, not by mirroring every app screen. Account administration, tenant policy, credential administration, billing, and live artifact promotion remain separate authority surfaces. The current workspace support matrix is:

Capability	MCP status
Create, list, rename, describe, and safely delete workspaces	Supported by Workspace MCP
Find and read accessible conversations	Supported by Workspace MCP
Build, deploy, inspect, and clean up private app drafts in a workspace	Supported by Build MCP
Create, post to, rename, archive, and safely delete workspace threads	Supported with separate chat read/write scopes
Read/write/delete workspace documents and maintenance guidance	Supported with separate content read/write/delete scopes
Create, update, complete, and remove workspace todos	Supported with a dedicated todo-write scope
List/read/bind/unbind workspace skills	Supported with separate skill read/write scopes
Inspect and change workspace or thread sharing/access	Supported with separate access-management authority
List/create/update/delete schedules and inspect recent runs	Supported with separate schedule read/write/delete scopes
Start, inspect, guide, retry, and cancel coding-agent tasks	Supported with separate workforce read/write scopes
Create, update, and archive explicit personal preferences	Supported with a write scope plus personal-memory confirmation capability
Read an enabled PestRoutes customer's reusable profile and bounded observed activity	Supported with customer_profiles:read plus the matching customer-profile capability
List pending questions, active work, and failed schedules	Supported through the workforce read scope

post_thread_message records a participant message for MCP-client collaboration; the external MCP client is the acting agent, so this operation does not also start a Topline internal-assistant turn. Destructive workspace, thread, content, and schedule operations require exact identifiers, and workspace/thread/content deletes use state-bound planning where the underlying state can drift.

New workspace operations should extend these capability families and call the same repositories and authorization predicates as the app. They must not proxy browser endpoints, accept a blanket "app parity" scope, or widen a user's tenant, ownership, sharing, secret, source, browser, or live-release authority.

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 Build MCP Hosted Tool Reference and Workspace MCP Tool Reference are the authoritative product inventories; the generated Harness reference is only their legacy compatibility union.

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.

External Build MCP clients read Storybook state with platform_get_design_system_state (storyboard:read). The local stdio helper offers platform_checkout_design_system, which downloads the tenant's published source at an exact commit to a new workspace directory. Codex or Claude Code can run npm ci and npm run storybook there, edit components and styles, and call platform_submit_design_system_draft with the published commit and last observed draft run ID. The submitted source is limited to Storybook components and tokens; package/configuration changes are rejected. Topline validates and builds it as a private draft. The local helper uses a content-derived request ID so an identical retry does not create another draft. Read state until the draft is ready, inspect its preview, then publish with the exact run, draft commit, and published commit. Local submissions can be published only by their submitting actor.

With a separately approved storyboard:write scope and a writable Topline Storybook conversation, platform_edit_design_system is an alternative path that starts Topline's guarded coding-agent draft workflow. Pass expectedDraftRunId from the last state read (null if none); stale and concurrent edits fail instead of appending twice. Managed drafts require that conversation at publication. Both paths use the same exact-commit publish check. A returned run ID is not proof that the draft is ready, and a timed-out write must be recovered from state before another write. Storybook's separate reference MCP endpoint remains read-only.

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.