Build a hosted MCP server

Topline can build and host a customer-owned MCP server as an artifact app, then connect that live artifact to the same Connected MCP servers management surface used for customer-managed remote MCP servers. This gives customers a governed way to add domain-specific tools to Topline chat and Cursor coding tasks without operating a separate MCP host, credential gateway, or agent-specific plugin.

Use a Topline coding task to create the artifact from the blessed FastMCP template. An external Build MCP client can inspect and deploy an already-complete MCP artifact package, but its generic platform_init_artifact_app tool does not currently scaffold the FastMCP template. On the promoted artifact, choose Connect to Topline. That action opens Account > Developer Access > Connected MCP servers with the artifact selected so a workspace MCP manager can decide which workflows and agents may use it.

What customers can build

A hosted MCP artifact can expose bounded, on-demand tools such as:

• read-only lookups, calculations, status checks, and domain-specific search;
• adapters that turn an approved external API into clear business tools;
• reviewed write actions such as creating a case or updating a work item;
• explicitly destructive actions that remain blocked or supervised until a workspace manager approves their policy; and
• one reusable tool surface for both Topline chat and selected Cursor coding agents.

For example, a customer can wrap an approved field-service API with tools such as find_customer, estimate_route_capacity, and create_follow_up. Tool names, typed schemas, descriptions, and safety annotations travel through MCP; Topline still owns the final authorization policy.

This contract is for request/response tools. Topline does not currently proxy MCP resources or prompts into workflows, and an MCP artifact is not a webhook receiver, background worker, ingestion pipeline, or arbitrary private-network gateway.

Supported contract

Area	Required behavior
Manifest	App-only manifestVersion: 2 with kind: "mcp_server". A legacy static artifact cannot claim this kind.
Template	A Topline coding task starts from the blessed fastmcp-server template. External Build MCP does not currently scaffold this template.
Runtime	Python on the artifact Lambda runtime, with a private operational page at /.
Framework	Topline-supported FastMCP exact-pinned to 3.4.7, including committed hash-locked dependencies.
Transport	Stateless JSON Streamable HTTP. No MCP session affinity is required.
Route	Exactly one handled API route at /_artifact/mcp; no alternate MCP path.
Machine authentication	mcpServer.auth.type is platform_managed_bearer. Topline creates and keeps the bearer private.
Artifact data	sourceBindings, datasets, and refreshSchedules must remain empty. Tools may use approved secretBindings for server-side external APIs.
Activation	Only a validated, promoted live deployment can be connected. Start from Connect to Topline on the live artifact; Developer Access then handles creation, tool review, workflow enablement, and agent assignment.
Consumers	Chat and Coding are enabled independently. The connection can be limited to selected agents on those enabled surfaces.

The required MCP-specific manifest fields are:

{
  "manifestVersion": 2,
  "kind": "mcp_server",
  "runtime": {
    "target": "aws_lambda_function_url",
    "language": "python"
  },
  "routes": [
    { "path": "/", "kind": "page", "handler": "src.app:app" },
    { "path": "/_artifact/mcp", "kind": "api", "handler": "src.app:app" }
  ],
  "sourceBindings": [],
  "datasets": [],
  "refreshSchedules": [],
  "mcpServer": {
    "framework": "fastmcp",
    "frameworkVersion": "3.4.7",
    "transport": "streamable_http",
    "stateless": true,
    "responseMode": "json",
    "route": "/_artifact/mcp",
    "auth": { "type": "platform_managed_bearer" }
  },
  "viewerPolicy": "private"
}

This excerpt is not a complete artifact manifest. The blessed template also contains required identity, build, validation, environment, and packaging fields. Have a Topline coding task copy that template; do not reconstruct a deployable package from this excerpt.

Build and connect

1. Start a Topline coding task and ask it to create the server from the blessed fastmcp-server template. If a complete package already exists locally, an external Build MCP client may inspect and deploy it without scaffolding.
2. Add typed tools in src/app.py. Keep descriptions concise and mark read-only, idempotent, open-world, and destructive behavior honestly. Update src/check.py at the same time: its expected discovery catalog, representative tool call, and annotation assertions must match the authored tools. Adding a tool without updating these exact checks intentionally fails local validation.
3. Add approved secretBindings only when server-side tools must call an external API. Never add the Topline MCP machine credential as a binding.
4. In the Topline coding workspace, run node scripts/artifacts/validate-local --dir <appDir> from the repository root. This runs the hash-locked build, HTTP initialization, discovery, representative tool call, fresh-client statelessness, and annotation checks. An external Build MCP client working from an already-complete package should use platform_inspect_artifact_app, then deploy with the inspected bundle hash; the trusted server performs the full manifest validation.
5. Deploy a private draft through the artifact lifecycle, run trusted smoke and validation, and leave live promotion to the operator.
6. After promotion, open the live artifact and choose Connect to Topline. This is the hosted-artifact connection entry point. It opens Developer Access > Connected MCP servers with that artifact selected; the generic new-server form does not discover hosted artifacts.
7. Choose Chat, Coding, or both, then choose all eligible agents or selected agents. Both surfaces may remain off while tools are reviewed.
8. Run the connection check. Every new tool starts blocked; classify each as read, write, or destructive and choose blocked, supervised, or autonomous access.
9. Start a new coding task after review when Cursor should receive the tools. Coding-task grants snapshot the exact reviewed connection, deployment, schemas, assignments, and policy.

The artifact cannot connect or approve itself. A user needs mcp.connections.manage to create the workspace connection and review its tools.

Authentication and data boundaries

Topline owns two separate credential paths:

• The MCP machine bearer authenticates Topline to the live artifact. Topline creates it, omits it from the general Credentials library, never returns it to the browser or coding agent, and uses it only through the brokered connection.
• A declared artifact secretBinding lets server-side tool code call one approved external API. It does not authorize Topline APIs, artifact data callbacks, connection management, or tool approval.

The only machine-ingress exception is the exact live /_artifact/mcp route. Ordinary artifact routes still require their normal viewer/session boundary. The MCP route does not create a general webhook contract, forward arbitrary headers, or authorize calls to /_artifact/data/*.

If a tool needs Topline-owned datasets, recurring synchronization, queues, private-network access, or durable background work, implement that capability as a reviewed connector or platform service and expose only the bounded tool operation through MCP.

Review and lifecycle behavior

The connection uses the same customer-managed MCP policy as any other connected server:

• Needs tool review means discovery found a new or changed tool definition that has not been classified. Classification does not itself grant access.
• Ready means discovery is current and every discovered tool definition has been classified. A tool is usable only when its access policy is not blocked, its workflow surface is enabled, and the calling agent is eligible.
• Recheck required means promotion or rollback changed the live code. Old approvals and coding grants cannot authorize the new deployment.
• Unavailable means there is no valid promoted MCP deployment. Republish a valid version or disconnect.
• Disconnecting means credential revocation has started and can be retried safely if the provider operation was ambiguous.

Promotion and rollback fail closed: Topline binds each broker call to the exact deployment authorized for that call. A changed live version cannot receive an already-approved call intended for older code. Run the connection check again, review any changed tool schemas, and start a new coding task after the new version is ready.

A linked artifact cannot be deleted until its managed MCP connection is disconnected. This preserves connection policy and audit history instead of silently deleting the management record.

Current limits

• Tools only; MCP prompts, resources, and tasks are recorded for compatibility but are not proxied into chat or coding workflows.
• No artifact sourceBindings, datasets, or refresh schedules.
• No direct Postgres, Topline API, AWS control-plane, or browser access from tool code.
• No arbitrary headers, caller-selected credentials, self-connection, self-approval, or automatic live promotion.
• No webhook delivery, queue consumer, long-running worker, or general private-network transport.

For the complete customer-managed connection and OAuth policy, see the MCP server reference. For packaging and deploying artifact drafts from an external client, see Build MCP.