# Topline Workspace MCP

Use Workspace MCP when an external MCP client needs current, permission-filtered
Topline context. It can find workspaces and visible conversations, search Topline
documentation, read approved preferences and company context, resolve glossary
terms, and submit explicitly requested knowledge changes for review.

Workspace MCP does not package or deploy artifact apps. Use
[Build MCP](/docs/build-mcp-guide) for that workflow.

## Who this guide is for

This guide is for a Topline operator connecting Codex, Claude Code, or another
Streamable HTTP MCP client. You need access to **Account > Developer Access**
and the scopes required for the information you intend to use.

## Connect your client

1. Open **Account > Developer Access** in Topline.
2. Find **Topline Workspace MCP**.
3. Choose your client and copy its generated setup snippet. The snippet points
   to your tenant's `/mcp/workspace` endpoint and contains no secret.
4. Start or reload the client. Complete browser sign-in and approve only the
   scopes you need.
5. In Developer Access, choose **Verify connection** and copy the one-time
   instruction into that same client.
6. Confirm that Developer Access reports the connection as verified.

For example, a Codex configuration has this shape. Always copy the actual URL
from Developer Access instead of typing it from memory.

```toml
[mcp_servers.topline-workspace]
url = "https://your-topline-origin.example/mcp/workspace"
```

OAuth approval is bound to Workspace MCP. A Build MCP authorization cannot be
reused here.

## Complete a first read-only workflow

Ask the client to perform this sequence:

1. Call `list_workspaces` and choose an accessible workspace.
2. Call `search_conversations` with that workspace and a phrase from a visible
   conversation title or message.
3. Call `read_conversation` with the returned conversation ID.
4. If more history is needed, pass `nextBeforeMessageId` into the next read.

Success means the client returns only conversations and visible message text
that you can access in Topline. Responses identify the owning workspace,
indicate truncated messages, and omit hidden runtime context and tool payloads.

## Find product and company context

Use the narrowest read tool for the question:

| Need | Start with |
| --- | --- |
| A Topline feature, API, MCP tool, or error | `platform_search_documentation` |
| A known documentation result | `platform_read_documentation` |
| An approved response preference | `read_preferences` |
| Permission-filtered company context | `search_context` |
| A company term or abbreviation | `lookup_glossary` or `search_glossary` |
| Visible text in one conversation | `search_conversation_messages` |

Searches and reads are bounded. Follow the returned cursor instead of widening
the request or attempting to bypass a limit.

## Make a reviewed knowledge change

Read access does not imply write access. Glossary and company-knowledge changes
require the corresponding scope, operator capability, and an explicit request.

- Use `create_glossary_term` or `update_glossary_term` only when the operator
  explicitly asks to publish that glossary change.
- Use `propose_company_knowledge` to submit cited knowledge for review.
- Use `company_knowledge_status` to follow its review state.
- Use `publish_company_knowledge` only when the operator explicitly requests
  that workflow and the connection has the required authority.
- `undo_company_knowledge` is destructive because it archives published
  knowledge and removes it from retrieval.

Never broaden a token or switch credentials merely because a write was denied.

## Troubleshooting

### The client cannot connect

1. Copy the Workspace snippet again from Developer Access.
2. Confirm the URL ends in `/mcp/workspace`, uses HTTPS, and is not the legacy
   `/mcp/harness` route.
3. Restart the client so it reloads MCP configuration.
4. Complete OAuth again if the authorization expired or was revoked.
5. Check the status: `401` means authentication is missing or invalid; `403`
   means the signed-in operator lacks the requested scope or capability; `404`
   usually means the endpoint is wrong.

### A tool is missing

Refresh tool discovery and confirm the client is connected to Workspace MCP.
Tool availability depends on granted scopes and operator capabilities. Compare
the discovered list with the [generated MCP tool reference](/docs/generated-mcp-tools).

### A conversation or workspace is missing

Open the same item in Topline as the signed-in operator. Workspace MCP enforces
the same tenant, ownership, sharing, and scope boundaries as the product. If it
is not visible there, the MCP server will not return it.

### Search returns too little history

Use `nextCursor` for additional conversation results and
`nextBeforeMessageId` for older messages. Individual visible messages may be
truncated at 4,000 characters, and transcript searches inspect bounded windows.

### A write is denied

Treat the denial as authoritative. Confirm the operator asked for the change,
the OAuth grant includes the write scope, and the operator has the required
glossary or company-knowledge capability. Do not substitute a broader account.

## Security and support evidence

- Do not place access tokens, refresh tokens, cookies, customer rows, raw PII,
  or typed browser values in prompts, logs, screenshots, or support requests.
- Revoke unused authorizations from Developer Access.
- Treat returned context as tenant data and follow the customer's retention
  policy.
- For support, provide the endpoint, tool name, timestamp, HTTP or JSON-RPC
  status, request ID when available, and a redacted description of the request.

For protocol behavior, scopes, and the complete server inventory, see the
[MCP server reference](/docs/mcp-server-reference).