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

[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.

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.