Getting Started

This section explains how to install the plugin, choose a transport mode, and debug common connection problems.

When to read this page: you are setting up the plugin, connecting an MCP client, or deciding between HTTP and stdio.

Related pages:

• Deployment
• HTTPS
• Troubleshooting
• Common Tasks

Reading Order

1. Deployment
2. HTTPS if you need TLS
3. Troubleshooting if the client cannot connect

What This Section Covers

• Installation from marketplace or source
• HTTP, stdio, and mcp-remote bridge choices
• Environment variables and default ports
• Docker, WSL, and LAN scenarios
• Quick checks when tools are not visible or calls fail

Scenario Skills And MCP Prompts

After connecting, MCP clients can discover scenario guidance through standard resources:

• siyuan://skills/index routes a task to the narrowest relevant skill.
• siyuan://skills/{name} returns the selected workflow and safety guide.

These resources are served by MCP and require no client-side installation. The server also exposes matching prompts with an optional task argument. Prompts are explicit, user-invoked workflow starters; clients should not assume that they run automatically.

If an agent supports installable SKILL.md packages, the npm CLI can install an equivalent local bundle:

# Existing default: CLI command conventions
siyuan-sisyphus skill install

# MCP tool-call conventions
siyuan-sisyphus skill install --bundle mcp

# Install both bundles
siyuan-sisyphus skill install --bundle all

skill list and skill read accept the same --bundle cli|mcp|all selector. Skills define task flow, path semantics, and safety rules; they do not replace action schemas. For exact current parameters, read siyuan://help/action/{tool}/{action} or call the tool's help action.

MCP 2026-07-28 And Legacy Clients

• stdio accepts both protocol eras automatically.
• HTTP routes 2026-07-28 requests to a stateless per-request handler and keeps stateful mcp-session-id sessions for legacy clients.
• Modern dangerous actions request confirmation through MCP multi-round-trip elicitation before dispatch. The form is requested only when the client advertises form elicitation. Clients without elicitation or with URL-only support skip the dialog; permissions, action switches, and strict preflight checks still apply.
• Browser requests with an Origin header are checked against localhost plus SIYUAN_MCP_ALLOWED_ORIGINS (comma-separated hostnames).
• The internal official-SiYuan MCP client uses automatic version negotiation.

SEP-2640 is a draft extension and is enabled by default for both HTTP and stdio transports, publishing all bundled workflow skills. For the built-in HTTP server, it can be toggled under Connection Config → HTTP/HTTPS Connection → Skills over MCP. Standalone servers can set SIYUAN_MCP_SKILLS_EXTENSION=false to disable it. This advertises io.modelcontextprotocol/skills and enables skills/list, skills/get, and all bundled skill:// resources. The regular siyuan://skills/* resources continue to work whether the extension is enabled or not.

The repository's validated Codex wrapper lives at agent-plugin/siyuan-sisyphus. Its MCP config points to http://127.0.0.1:36806/mcp; add client-side bearer authentication if your server requires SIYUAN_MCP_TOKEN.

Next Steps

After setup, try the Common Tasks page for quick MCP/CLI examples.

DSH (DeepSeek Harness)

Choose DSH alongside the other MCP clients in plugin settings, select HTTP/HTTPS or stdio, and copy the generated Cordis YAML patch. Desktop configuration lives at ~/.dsh/profiles/desktop/cordis.patch.yml; other profiles include web, headless, and tui. Merge by entry id, preserving other patches. Do not wrap the configuration in mcpServers or duplicate a serverName.

This example has no authentication; use the URL and port generated by your settings:

- insert:
    - id: mcp-siyuan-sisyphus
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: siyuan-sisyphus
        transport: streamable-http
        url: http://127.0.0.1:36806/mcp
        failOnStartupError: true

Changes hot-reload without restarting. Tool names follow mcp__siyuan-sisyphus__<tool>, for example mcp__siyuan-sisyphus__fs. The snippet sets failOnStartupError: true, so start the SiYuan MCP service first.

With HTTP authentication enabled, settings generate Authorization: !!js "'Bearer ' + process.env.MCP_TOKEN"; authenticated stdio uses SIYUAN_TOKEN: !!js process.env.SIYUAN_TOKEN for the kernel API token. Make these variables available to the DSH process instead of writing literal secrets into YAML. Exporting them in a terminal may not affect an already running desktop app.