# 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](/docs/build-mcp-guide) 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:

```json
{
  "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](/docs/mcp-server-reference). For packaging and deploying
artifact drafts from an external client, see [Build MCP](/docs/build-mcp-guide).