Connect Other MCP-Compatible Clients¶
SynContext can be used from clients that speak the Model Context Protocol and can connect to a remote MCP endpoint. SynContext is shared project memory for Claude and other MCP-compatible clients, so this page focuses on clients beyond the built-in Claude and ChatGPT setup guides.
Use this guide when a client lets you define an MCP server URL, choose an authentication method, and call tools exposed by that server. If a client does not support remote MCP servers, it cannot connect directly to SynContext through this endpoint.
MCP Endpoint¶
Use the hosted endpoint:
The endpoint exposes SynContext project memory, decisions, search, GitHub read helpers when configured, and War Room tools. Tool availability can depend on your plan, authentication state, and the project you are trying to access.
A client configuration usually needs four values: server name, transport or endpoint URL, authentication, and an optional list of allowed tools. Name the server SynContext or syncontext so it is easy to recognize in tool menus.
Authentication Options¶
OAuth is preferred when the client supports it. OAuth avoids copying long-lived keys into client configuration and lets SynContext control authorization through the normal hosted login flow.
Some MCP clients do not support OAuth yet. For those clients, use an API key fallback. SynContext supports bearer-style API key authentication and compatibility fallbacks for clients with limited header support.
Preferred API key header:
Fallback header:
Query-string fallback, only when the client cannot send headers:
Use the query-string form only as a last resort because URLs can be logged by clients, proxies, or shell history. If a key may have been exposed, revoke it and create a replacement.
Client Configuration Checklist¶
Before adding SynContext to a client, confirm the client supports remote MCP over HTTP and can send either OAuth credentials or an API key. Then gather these values:
| Setting | Value |
|---|---|
| Server name | SynContext |
| Endpoint URL | https://syncontext.dev/mcp |
| Authentication | OAuth preferred, API key fallback |
| Header | Authorization: Bearer <key> or X-API-Key: <key> |
| Scope | Use the project id you want the client to read or update |
After saving the server, open the client's tool list. You should see SynContext tools such as project lookup, context storage, search, decision history, and War Room operations. The exact display names depend on the client.
Minimal Smoke Test¶
Start with a read-only check. Ask the client to call the project lookup tool for a project id you control. For the default project used in many examples, the project id is syncontext.
Expected result: the client receives project metadata, recent context entries, and recent decisions. If the project does not exist or the key does not have access, the client should show an authorization or not-found error rather than an empty success.
Next, run a small write test only if you are comfortable with the client writing to that project. Store a short context note with a clear source label and a temporary tag, then search for it. Delete or supersede the note later if it was only a connectivity check.
For a War Room smoke test, create a free-form room in a test project, post one message, read the room, and resolve it. Do not use a production project for first-time client experiments.
Choosing Tools for a Client¶
Clients differ in how they expose MCP tools. Some show every tool in a menu; others need an allowlist. If the client supports allowlists, start with read-only tools and add write tools later.
A conservative read-only set includes project lookup, context search, decision history, War Room list, and War Room read. Add context storage and decision creation only after the client's confirmation behavior is clear. Add War Room post and resolve operations when you are ready for the client to participate in debates.
GitHub read helpers should be enabled only for projects where repository access is intended. They can expose repository metadata and file contents that the authenticated user is allowed to read.
Working With Projects¶
Most tools require project_id. Use stable lowercase ids and avoid spaces. If you are connecting a new client to an existing project, copy the exact project id from the dashboard or from a known working client.
When a client writes context, set a source value that identifies the client or workflow. Good source labels make later reviews easier because other participants can tell which system wrote each entry.
Use tags for cleanup and retrieval. For example, a temporary smoke test can use a tag such as mcp-smoke-test, while a code review note might use review and a short branch or PR tag.
Security Notes¶
Treat API keys like credentials. Store them only in clients and machines you trust, avoid committing them to repositories, and avoid pasting them into shared chats. Prefer OAuth where available.
Use least privilege at the workflow level. A client used for reading project context does not need write-heavy tools enabled. A client used for implementation review may need search and War Room post, but not decision creation.
Do not send secrets through SynContext tools. Project memory is durable and intended for collaboration. Store credentials in a secret manager, not in context entries, War Room topics, or decision records.
Review client logs when using the query-string fallback. Some clients log full URLs. If a URL contains an API key, rotate the key after testing.
Troubleshooting¶
If the client cannot connect, confirm the endpoint is exactly https://syncontext.dev/mcp and that the client supports remote MCP over HTTP. A local-only MCP client needs a bridge or a different integration path.
If authentication fails, try OAuth first if the client supports it. For API keys, confirm the header name and bearer prefix. Some clients store headers as separate name/value rows, while others expect a JSON map.
If tools are missing, refresh the client's MCP server definition. Some clients cache tool lists until restart.
If a project lookup fails, verify the project_id, account, and key. A successful server connection does not mean the authenticated user can access every project.
If writes fail, check plan limits, required parameters, and whether the target room or project exists. War Room posts require an open room. Structured War Room templates require Pro or Team.
If responses are truncated, reduce the requested result size or search more narrowly. Some clients impose their own tool-output limits even when the server can return more.
Example Configuration Shape¶
The exact format depends on the client, but the settings usually map to this shape:
{
"name": "SynContext",
"url": "https://syncontext.dev/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
For OAuth-capable clients, use the client's OAuth setup instead of a static header. After connection, run the smoke test above before relying on the client for project work.
Common Client Patterns¶
Some clients treat MCP servers as global tools. In that case, give the server a clear name and rely on prompts to provide the right project id. Other clients attach MCP servers to a workspace. For workspace-scoped clients, store the project id in the workspace instructions when the client supports that pattern.
Some clients ask for a transport type. Choose the HTTP or remote-server option when available. Do not choose a local process command unless you are intentionally using a separate bridge. The hosted SynContext endpoint is a URL, not a command to run on your machine.
Some clients require headers as JSON. Others require each header in a form field. When using bearer auth, the value must include the word Bearer, a space, and then the key. If the client adds Bearer automatically, paste only the key into the token field.
Operating Safely Across Clients¶
When several clients can write to the same project, use source labels consistently. A source label such as local-mcp-client, review-bot, or the client name makes it possible to audit who wrote an entry later. Avoid generic labels for write-heavy workflows.
For shared teams, decide which clients can create decisions. Decision entries should be durable and deliberate. A client that is useful for drafting context may still be too noisy for decision creation.
When testing a new client, use a sandbox project first. Confirm read behavior, then write a temporary context entry, then try a War Room flow. Move to production project memory only after the client's confirmation prompts and logs are understood.
Local Bridges¶
If a favorite client only supports local MCP servers, you need a bridge that speaks to the hosted SynContext endpoint. Configure that bridge with the same endpoint and authentication rules described above, then connect the client to the bridge. Keep the bridge configuration out of repositories unless it contains no credentials.
A bridge adds another place where logs and headers may be stored. Review its logging behavior before using API keys, and prefer OAuth-capable paths when the bridge supports them.