Loading…
syphon.json is the manifest file at the root of every Syphon package. It tells the registry what your server does, how to run it, and what environment it needs.
Create one with syphon init or write it by hand. Validation runs on syphon pack and syphon publish — all errors must be resolved before uploading.
| Field | Type | Req. | Description |
|---|---|---|---|
| name | string | yes | Lowercase, hyphens allowed. Scoped names like @org/name are supported. Regex: ^(@[a-z0-9-]+/)?[a-z0-9][a-z0-9-]{0,63}$ |
| version | string | yes | Semver string — must parse as a valid semver. Example: 1.2.3 |
| description | string | yes | 10–280 characters. Shown in search results and on the package page. |
| license | string | yes | SPDX identifier. Common values: MIT, Apache-2.0, GPL-3.0, ISC. |
| author | string | yes | Must match the username or display_name of the authenticated account. |
| runtime | enum | yes | One of: node, bun, python, deno, binary |
| entry | string | yes | Relative path to the main entrypoint. e.g. dist/index.js or my-binary |
| mcp_version | string | yes | The MCP SDK version your server targets. e.g. 1.0.0 |
| category | enum | yes | devtools | data | productivity | communication | search | cloud | database | ai | security | finance | other |
| tools | ToolDef[] | yes | At least one tool definition is required. See tools[] below. |
Each entry describes one MCP tool exposed by your server. This is metadata only — Syphon doesn't validate that the listed tools actually exist in your code.
| Field | Type | Req. | Description |
|---|---|---|---|
| name | string | yes | Lowercase letters, digits, underscores only. Regex: ^[a-z][a-z0-9_]{0,63}$ |
| description | string | yes | Min 10 characters. Shown to users browsing the registry. |
| params | string[] | no | Optional list of parameter names (informational). |
"tools": [
{
"name": "search_issues",
"description": "Searches GitHub issues by keyword and filters",
"params": ["query", "repo", "state", "labels"]
}
]Declares environment variables your server needs. Users see this list before installing.
| Field | Type | Req. | Description |
|---|---|---|---|
| name | string | yes | SCREAMING_SNAKE_CASE. Regex: ^[A-Z][A-Z0-9_]*$ |
| required | boolean | yes | true = server won't start without it; false = optional. |
| description | string | no | Human-readable explanation of what the variable is and where to get it. |
| default | string | no | Default value if not set. Only meaningful for required: false. |
"env": [
{
"name": "GITHUB_TOKEN",
"required": true,
"description": "GitHub PAT — create one at github.com/settings/tokens"
},
{
"name": "GITHUB_API_URL",
"required": false,
"default": "https://api.github.com",
"description": "Override for GitHub Enterprise"
}
]Declares which agent frameworks your server is compatible with. Used by syphon install --link and syphon link to wire the server into the correct config file.
| Value | Config file linked |
|---|---|
| claude-code | ~/.claude.json or project .mcp.json |
| claude-desktop | ~/Library/Application Support/Claude/claude_desktop_config.json |
| cursor | ~/.cursor/mcp.json |
| windsurf | ~/.codeium/windsurf/mcp_config.json |
| gemini-cli | ~/.gemini/settings.json |
| cline | ~/.cline/data/settings/cline_mcp_settings.json or Cline VS Code extension storage |
| codex | ~/.codex/config.toml |
| zed | ~/.config/zed/settings.json |
| continue | ~/.continue/config.yaml |
| vscode-mcp | ~/.vscode/mcp.json |
| goose | ~/.config/goose/config.yaml |
| kiro | ~/.kiro/settings/mcp.json |
| augment | ~/.augment/settings.json |
| langchain | manual SDK integration |
| crew-ai | manual SDK integration |
| openai-agents | manual SDK integration |
| generic | manual integration only |
| Field | Type | Req. | Description |
|---|---|---|---|
| homepage | string | no | URL of the project homepage. Must be a valid URL. |
| keywords | string[] | no | Up to 20 keywords. Improve search discoverability. |
| tags | string[] | no | Up to 10 release tags. Distinct from version tags — informational only in the manifest. |
| platforms | Platform[] | no | Default: ["linux-x86_64","macos-arm64","macos-x86_64"]. Values: linux-x86_64, linux-arm64, macos-x86_64, macos-arm64, win32-x64 |
| auth | enum | no | none | apikey | oauth | bearer — documents the auth method your server uses. |
| min_runtime_version | string | no | Minimum version of the runtime required (e.g. 18.0.0 for Node 18+). |
Optional. Declares the OS-level capabilities your server needs. Shown to users before install and enforced by future sandbox runtimes.
| Key | Description |
|---|---|
| fs.read | Array of glob paths the server may read. Use ["*"] for any path. |
| fs.write | Array of glob paths the server may write. |
| net.hosts | Array of hostnames the server may connect to. |
| net.deny_private | Block connections to private/loopback addresses (default: false). |
| exec.allow | true to allow any subprocess, or an array of allowed binary names. |
| env.read | Array of environment variable names the server may read. |
"permissions": {
"fs": { "read": ["*"], "write": [] },
"net": { "hosts": ["api.github.com"], "deny_private": true },
"exec": { "allow": ["git"] },
"env": { "read": ["GITHUB_TOKEN", "HOME"] }
}^(@[a-z0-9-]+/)?[a-z0-9][a-z0-9-]{0,63}$^[a-z][a-z0-9_]{0,63}$; each description ≥ 10 chars^[A-Z][A-Z0-9_]*$syphon pack --dry-run to see validation errors without touching the network.{
"name": "github-tools",
"version": "1.0.0",
"description": "GitHub API: manage issues, PRs, commits, repos, and releases from your AI agent",
"license": "MIT",
"author": "your-username",
"homepage": "https://github.com/your-username/github-tools",
"runtime": "node",
"entry": "dist/index.js",
"mcp_version": "1.0.0",
"category": "devtools",
"keywords": ["github", "git", "issues", "pull-requests"],
"frameworks": ["claude-code", "cursor", "windsurf", "generic"],
"platforms": ["linux-x86_64", "linux-arm64", "macos-arm64", "macos-x86_64"],
"tools": [
{ "name": "search_issues", "description": "Searches GitHub issues across repositories" },
{ "name": "create_issue", "description": "Creates a new GitHub issue" },
{ "name": "list_prs", "description": "Lists open pull requests for a repository" }
],
"env": [
{
"name": "GITHUB_TOKEN",
"required": true,
"description": "GitHub PAT — create at github.com/settings/tokens"
}
],
"permissions": {
"fs": { "read": ["*"], "write": [] },
"net": { "hosts": ["api.github.com"], "deny_private": true },
"exec": { "allow": ["git"] },
"env": { "read": ["GITHUB_TOKEN"] }
}
}