Skip to content

USER_GUIDE.md

Latest commit

 

History

History
188 lines (112 loc) · 7.12 KB

USER_GUIDE.md

File metadata and controls

188 lines (112 loc) · 7.12 KB

MCP Synapse User Guide

This guide describes the current MCP Synapse desktop product surface for the v0.6.1 Windows release. It is written for developers who want a step-by-step path from install to first working connection without relying on hidden defaults or hosted relay infrastructure.

MCP Synapse is BYOK and local-first. You bring your own provider account and credentials, the app does not maintain a shared key pool, and the desktop product does not proxy your requests through a hosted MCP Synapse cloud.

1. Prerequisites

Before you install MCP Synapse, make sure the following are ready:

  • Windows 10 or Windows 11
  • One supported AI provider account with valid credentials
  • Permission to install a desktop app on your machine

The current first-release provider surface includes:

  • Vertex AI
  • OpenAI
  • Azure OpenAI
  • HuggingFace
  • Ollama

Bedrock is not part of the current first-release provider surface.

2. Install

Use the official v0.6.1 release package:

  • NSIS installer: MCP Synapse_0.6.1_x64-setup.exe
  • MSI installer: MCP Synapse_0.6.1_x64_en-US.msi
  • SHA256 manifest: SHA256SUMS.txt

Release page:

  • https://github.com/solidsynapse/MCP-Synapse/releases/tag/v0.6.1

SmartScreen and unsigned notice

This release lane remains temporarily unsigned. That means Windows SmartScreen may warn you before first launch even when the package is expected and intact.

If SmartScreen appears:

  1. Confirm that you downloaded the installer from the official v0.6.1 release page.
  2. Verify the installer hash against SHA256SUMS.txt.
  3. Use the Windows "More info" path only after the hash and source both match.

This is normal for the current lane and is explicitly documented in:

  • docs/release/releases/v0.6.1/INSTALL_RUN_NOTES.md
  • docs/release/releases/v0.6.1/UNSIGNED_NOTICE.md

SHA256 verification

Use PowerShell to verify the downloaded artifact before first run:

Get-FileHash 'C:\Path\To\MCP Synapse_0.6.1_x64-setup.exe' -Algorithm SHA256

Or, if you downloaded the MSI:

Get-FileHash 'C:\Path\To\MCP Synapse_0.6.1_x64_en-US.msi' -Algorithm SHA256

Compare the hash output with the matching entry in SHA256SUMS.txt.

Install flow

  1. Download either the NSIS installer or the MSI package from the official v0.6.1 release.
  2. Verify the package hash before running it.
  3. Keep the default install location unless your environment requires a custom path.
  4. Finish setup and launch MCP Synapse from the Start Menu shortcut.

3. First Connection

After installation, open MCP Synapse and go to the Connections page.

Create a bridge

The Connections surface is where you create, edit, start, stop, and delete provider-backed bridges. It also exposes schema-guided forms, preflight validation, and MCP config export.

When creating a connection, the exact fields depend on the provider you choose. Common examples:

  • Vertex AI: project_id, location, model_id, and a service-account JSON credentials path
  • OpenAI: model_id and api_key
  • Azure OpenAI: endpoint, deployment_name, api_key, and the required API version when requested
  • HuggingFace: endpoint or model settings plus the required access token
  • Ollama: local base URL and the installed local model name

Enter credentials

Credentials stay local to your machine. MCP Synapse does not operate a shared key pool and does not silently move secrets into a hosted service.

For repeated use, you can save credentials through the Vault helper. Vault is keyring-backed and local-only.

Run preflight

Before you rely on a connection, use Preflight. This validates that the current provider form, credentials, and basic runtime reachability are coherent enough for the connection to start.

If preflight fails, fix that first. Do not assume the bridge will behave correctly later if the validation step is already red.

Copy Config

After the connection is valid, use Copy Config. MCP Synapse generates the JSON snippet you can paste into your IDE MCP configuration.

The app does not edit your IDE config file for you. It gives you the exact MCP JSON so you can paste it into the tool you actually use.

4. Using the App

Dashboard

The Dashboard is the quick operational view. It shows cost, latency-adjacent operational visibility, health alerts, recent requests, KPI cards, and cost trends so you can see current behavior without opening deeper tools first.

It is a read-oriented surface. It does not secretly retry, reroute, or repair provider behavior behind your back.

Usage Summary and History

The Usage surfaces are for request visibility and reporting. You can filter, inspect recent records, and export CSV data when you need a local audit trail or a quick handoff to analysis tools.

Cost visibility stays explicit through the cost_source badge:

  • ACTUAL means the provider supplied real usage pricing data
  • ESTIMATED means the app calculated a best-effort estimate
  • UNKNOWN means pricing could not be resolved and is not silently treated as zero

Policies

The current Policies surface includes:

  • Persona Lite
  • Optimizations

Persona Lite applies deterministic preset-based system prompt behavior. Optimizations currently expose context caching and request deduplication controls.

This surface is intentionally narrow. Full policy orchestration and advanced persona tooling are not part of the current lane.

Resilience

The current Resilience surface includes:

  • Interceptors
  • Budget Guard

Interceptors currently cover persisted JSON syntax-repair behavior. Budget Guard is monitor-only in the current lane, so it is useful for visibility and planning, not for hard request enforcement yet.

Vault

Vault helps you save, list, select, and delete local credential entries. It is keyring-backed and local-only.

Vault selection is metadata-first. The UI does not expose raw secrets back through the response surface.

5. Troubleshooting

Preflight FAIL

If preflight fails:

  1. Re-check the provider-specific fields.
  2. Confirm the credential source is the one you intended to use.
  3. Verify the selected model, endpoint, project, or deployment name is valid for that provider.
  4. Re-run preflight before attempting to start or export the bridge.

SmartScreen blocker

If Windows blocks launch:

  1. Confirm the installer came from the official v0.6.1 release page.
  2. Verify the SHA256 hash.
  3. Review the unsigned notice.
  4. Proceed only after source and hash both match.

Provider connection error

If the bridge starts but provider requests fail:

  1. Re-check the credential fields for the selected provider.
  2. Confirm the model or deployment identifier is valid in your account.
  3. For local providers such as Ollama, confirm the local runtime is actually running.
  4. Re-run preflight and review the connection settings instead of guessing.

Known issues

Before you treat a behavior as a new bug, review the current release-known issues:

  • docs/release/releases/v0.6.1/KNOWN_ISSUES.md

Current known deferred items include Bedrock remaining blocked from the first-release surface, steady-state worker memory optimization being deferred, and commercial code signing remaining outside the current lane.