API Reference¶

SynContext exposes 21 MCP tools over Streamable HTTP: 10 core tools, 6 GitHub tools, and 5 War Room tools, plus REST/OAuth endpoints for the dashboard and marketplace clients.

MCP Endpoint¶

URL: https://syncontext.dev/mcp

Authentication (supported modes):

Method	Format	Use case
OAuth 2.1	Dynamic Client Registration + PKCE S256	OAuth-capable remote MCP clients, including marketplace connector flows
Header	`X-API-Key: YOUR_KEY`	Claude Desktop, Claude Code, manual MCP clients
Bearer	`Authorization: Bearer SESSION_TOKEN`	Dashboard sessions
Query	`?key=YOUR_KEY`	API-key fallback for clients that cannot send custom headers

MCP Tools¶

The MCP server publishes tool annotations from context_hub/server.py. These values are part of the runtime tool registry and are listed here so reviewers can confirm the documented tool surface matches the server behavior.

Tool	Title	readOnlyHint	destructiveHint	idempotentHint	openWorldHint
`search`	Search Context Hub	true	false	true	false
`fetch`	Fetch Context Entry	true	false	true	false
`hub_list_projects`	List All Projects	true	false	true	false
`hub_get_project`	Get Project Details	true	false	true	false
`hub_store_context`	Store Context Entry	false	true	false	true
`hub_update_status`	Update Project Status	false	true	false	true
`hub_log_decision`	Log a Decision	false	true	false	true
`hub_get_decisions`	Get Decision History	true	false	true	false
`hub_update_context`	Update Context Entry	false	true	false	true
`hub_export_project`	Export Project	true	false	true	false
`hub_github_repos`	List GitHub Repos	true	false	true	true
`hub_github_tree`	View Repo File Tree	true	false	true	true
`hub_github_read`	Read GitHub File	true	false	true	true
`hub_github_search`	Search Code in Repo	true	false	true	true
`hub_github_commits`	View Recent Commits	true	false	true	true
`hub_github_create_pr`	Create Pull Request	false	true	false	true
`hub_create_war_room`	Create War Room	false	true	false	true
`hub_post_war_message`	Post War Room Message	false	true	false	true
`hub_read_war_room`	Read War Room	true	false	true	false
`hub_resolve_war_room`	Resolve War Room	false	true	false	true
`hub_list_war_rooms`	List War Rooms	true	false	true	false

search¶

Keyword search over the titles, tags, and categories of your context entries. Entry bodies are encrypted at rest and not keyword-indexed; full-content search is available via semantic/hybrid modes on the REST API (see Note).

Parameter	Type	Required	Description
query	string	yes	Search query

Note: Semantic and hybrid search modes are available via the REST API (GET /api/context?q=...&mode=semantic), but the MCP tool uses keyword search only.

Example response:

{
  "results": [
    {
      "id": 1,
      "project_id": "my-app",
      "title": "Tech stack",
      "snippet": "React + Vite frontend, Python backend...",
      "source": "claude",
      "created_at": "2026-03-25T14:30:00Z"
    }
  ]
}

fetch¶

Get the full content of a context entry by ID.

Parameter	Type	Required	Description
id	string	yes	Entry ID (numeric)

Example response:

{
  "id": 1,
  "project_id": "my-app",
  "title": "Tech stack",
  "content": "Full content of the entry...",
  "category": "note",
  "source": "claude",
  "tags": "[\"frontend\", \"backend\"]",
  "created_at": "2026-03-25T14:30:00Z"
}

hub_list_projects¶

List all your projects with status and timestamps.

No parameters.

Example response:

{
  "projects": [
    {
      "id": "my-app",
      "name": "My App",
      "status": "active",
      "created_at": "2026-03-25T10:00:00Z",
      "updated_at": "2026-03-25T14:30:00Z"
    }
  ],
  "total": 1
}

hub_get_project¶

Get full details of a project including the 10 most recent context entries and 5 most recent decisions.

Parameter	Type	Required	Description
project_id	string	yes	Project ID

hub_store_context¶

Store a new context entry. Auto-creates the project if it doesn't exist.

Parameter	Type	Required	Default	Description
project_id	string	yes	—	Project to store in
title	string	yes	—	Entry title
content	string	yes	—	Entry content (max 500KB)
category	string	no	note	`note`, `doc`, `status`, `code`, `decision`
source	string	no	unknown	Who created it (e.g., `claude`, `chatgpt`)
tags	list	no	[]	List of tag strings

Example response:

{
  "stored": true,
  "entry": {
    "id": 5,
    "project_id": "my-app",
    "title": "API design notes",
    "category": "doc",
    "source": "claude",
    "created_at": "2026-03-25T15:00:00Z"
  }
}

hub_update_context¶

Update an existing context entry. The previous version is saved in history and can be rolled back.

Parameter	Type	Required	Description
entry_id	int	yes	Entry ID to update
title	string	no	New title
content	string	no	New content (max 500KB)
source	string	no	Who made the change

Example response:

{
  "updated": true,
  "entry": {
    "id": 5,
    "title": "API design notes v2",
    "updated_at": "2026-03-25T16:00:00Z"
  }
}

hub_update_status¶

Update the status of a project.

Parameter	Type	Required	Description
project_id	string	yes	Project ID
status	string	yes	`active`, `paused`, `blocked`, `completed`, `archived`

hub_log_decision¶

Record a project decision with rationale and alternatives considered.

Parameter	Type	Required	Default	Description
project_id	string	yes	—	Project ID
title	string	yes	—	Decision title
decision	string	yes	—	What was decided
rationale	string	no	""	Why this decision was made
alternatives	list	no	[]	Alternatives that were considered
decided_by	string	no	unknown	Who made the decision

hub_get_decisions¶

Get the decision history for a project, newest first.

Parameter	Type	Required	Default	Description
project_id	string	yes	—	Project ID
limit	int	no	20	Max results

hub_export_project¶

Export a complete project as JSON, including all context entries and decisions.

Parameter	Type	Required	Description
project_id	string	yes	Project ID to export

Returns a JSON object with the project metadata, all context entries (decrypted), and all decisions.

GitHub Tools (6, Pro/Team)¶

Tool	Type	Description
`hub_github_repos`	Read	List GitHub repositories accessible with the connected token
`hub_github_tree`	Read	View file structure of a linked repository
`hub_github_read`	Read	Read file contents from a linked repository
`hub_github_search`	Read	Search code in a linked repository
`hub_github_commits`	Read	View recent commits from a linked repository
`hub_github_create_pr`	Write	Create a pull request with a single file change

GitHub tools use a user-provided fine-grained Personal Access Token that is encrypted at rest. SynContext does not implement GitHub OAuth for repository connections.

War Room Tools (5, Pro/Team)¶

Tool	Type	Description
`hub_create_war_room`	Write	Create a structured AI debate room for a project
`hub_post_war_message`	Write	Post a message to an active War Room debate
`hub_read_war_room`	Read	Read War Room messages, consensus, and project context
`hub_resolve_war_room`	Write	Resolve a War Room with a final conclusion
`hub_list_war_rooms`	Read	List War Rooms for a project

REST API¶

The REST API is used by the web dashboard and is available for programmatic access.

Base URL: https://syncontext.dev/api

Authentication endpoints (public)¶

Method	Path	Description
POST	`/api/auth/register`	Create account, returns API key
POST	`/api/auth/login`	Login, returns session token
POST	`/api/auth/logout`	Invalidate current session

User endpoints¶

Method	Path	Description
GET	`/api/me`	Current user info + usage stats
POST	`/api/me/regenerate-key`	Generate new API key (invalidates old)

Project endpoints¶

Method	Path	Description
GET	`/api/projects`	List all projects
POST	`/api/projects`	Create or update project
GET	`/api/projects/{id}`	Get project with recent entries
PATCH	`/api/projects/{id}/status`	Update project status
DELETE	`/api/projects/{id}`	Delete project and all data

Context endpoints¶

Method	Path	Description
GET	`/api/context?q=...&mode=...`	Search (keyword/semantic/hybrid)
POST	`/api/context`	Store new entry
GET	`/api/context/{id}`	Fetch entry by ID
PUT	`/api/context/{id}`	Update entry (saves version)
DELETE	`/api/context/{id}`	Delete entry
GET	`/api/context/{id}/versions`	Version history
POST	`/api/context/{id}/rollback`	Rollback to version

Decision endpoints¶

Method	Path	Description
GET	`/api/decisions/{project_id}`	List decisions
POST	`/api/decisions`	Log a decision

Other endpoints¶

Method	Path	Description
GET	`/api/stats`	Usage statistics
GET	`/api/audit`	Audit log (Pro+)
GET	`/api/export`	Export all projects
GET	`/api/export/{id}`	Export single project
POST	`/api/import`	Import project JSON
POST	`/api/import/chatgpt`	Import ChatGPT memory
GET	`/api/webhooks`	List webhooks
POST	`/api/webhooks`	Create webhook
DELETE	`/api/webhooks/{id}`	Delete webhook
GET	`/api/billing/status`	Billing status
POST	`/api/billing/checkout`	Start Stripe checkout
POST	`/api/billing/portal`	Stripe customer portal

Health check¶

GET https://syncontext.dev/health
→ {"status": "ok", "service": "syncontext"}

No authentication required. Use this to verify the service is running.