MCP server (@devicesdk/mcp)

MCP server (@devicesdk/mcp)

Drive DeviceSDK from Claude, Cursor, Continue, Windsurf and other MCP-aware coding agents

@devicesdk/mcp is a Model Context Protocol server that exposes DeviceSDK as a set of tools your AI agent can call directly — list devices, deploy scripts, tail logs, set env vars, search the docs. The agent never has to learn the shell.

It’s a thin wrapper over the devicesdk CLI’s --json mode, so you get the same auth, the same error messages, and the same { success, result | error, code, docs } shape the API returns.

Quickstart

If you ran devicesdk init recently, you already have a .mcp.json in your project pointing at @devicesdk/mcp — open the project in any MCP-aware tool and it just works.

For an existing project, drop this into a .mcp.json at the project root:

{
  "mcpServers": {
    "devicesdk": {
      "command": "npx",
      "args": ["-y", "@devicesdk/mcp"]
    }
  }
}

Then reload your agent and run devicesdk login once so the MCP server can find your auth token.

Install per host

Claude Code

If you use Claude Code in a project that has .mcp.json, the server registers automatically on session start. To register globally instead:

claude mcp add devicesdk -- npx -y @devicesdk/mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "devicesdk": {
      "command": "npx",
      "args": ["-y", "@devicesdk/mcp"]
    }
  }
}

Restart Claude Desktop. The DeviceSDK tools appear in the 🔨 picker.

Cursor

Cursor reads .mcp.json from the project root (same shape as above). It also supports a global ~/.cursor/mcp.json. Reload the workspace after adding.

Continue.dev

Add to your ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@devicesdk/mcp"]
        }
      }
    ]
  }
}

Windsurf, Zed, JetBrains Junie, others

Any MCP-aware client that accepts a stdio server with a command + args will work. Use the same npx -y @devicesdk/mcp invocation.

Authentication

The MCP server inherits the CLI’s authentication. In order of precedence:

  1. DEVICESDK_TOKEN environment variable — best for CI or when you want a tighter-scoped token for the agent than for your CLI.
  2. ~/.devicesdk/auth.json — written by devicesdk login. Refresh tokens rotate automatically.

If neither is present, every tool returns { success: false, code: "missing_credentials", docs: "..." }.

To scope an agent more tightly, generate a token in the dashboard’s Tokens page and pass it through your MCP host’s environment. For Claude Desktop, that means adding an env block in the config:

{
  "mcpServers": {
    "devicesdk": {
      "command": "npx",
      "args": ["-y", "@devicesdk/mcp"],
      "env": { "DEVICESDK_TOKEN": "dsdk_…" }
    }
  }
}

Tools

Tool What it does
devicesdk_whoami Show the currently-authenticated user.
devicesdk_status List devices in a project with their connection state, current version, and last-seen time. Defaults to the project in devicesdk.ts in the cwd.
devicesdk_logs_tail Fetch the most recent N log entries for a device (max 100). Filters by level. Returns the same shape as devicesdk logs --json.
devicesdk_env_list List env var keys for a project. The API never returns values, so neither does this tool — read them inside your script with this.env.VARS.get.
devicesdk_env_set Set one or more KEY=VALUE pairs on a project.
devicesdk_deploy Build and deploy device scripts. Supports --dry-run and per-device targeting.
devicesdk_docs_search Resolve a free-text query to relevant URLs from /llms.txt. Use to point yourself at canonical references for further reading.

Every tool returns { success, result | error, code?, docs? }. On success: false the docs field points at the page on this site explaining the error.

Example session

You: list my devices in the orchard project, then tail the last 20 errors from the broken one

Agent: [calls devicesdk_status → orchard has 4 devices: sensor-east is offline]
       [calls devicesdk_logs_tail with level=error, lines=20, project=orchard, device=sensor-east]
       sensor-east lost connectivity 14 minutes ago. The last 20 error logs show
       "BME280 not detected at 0x76" repeating every minute since 09:14 UTC. That
       error pattern matches the I2C-wiring case in /docs/recipes/read-bme280/ —
       check the SDA/SCL wires haven't come loose.

Troubleshooting

  • “command not found: devicesdk” during a tool call. The server shells out to the CLI, so the CLI must be on PATH (or installed via the @devicesdk/mcp package’s bundled dependency). Run npm install -g @devicesdk/cli if you don’t have it project-locally, or run the agent from inside a project where devicesdk is available via npx.
  • Every tool returns missing_credentials. Run devicesdk login once, or set DEVICESDK_TOKEN in the MCP host’s env block.
  • Tools list shows up empty. Some hosts cache the tool catalog. Restart the agent / reload the workspace after editing .mcp.json.
  • Tools work but the agent doesn’t pick the right one. Drop a hint in your prompt: “use the devicesdk_status tool to check connectivity, then devicesdk_logs_tail to see why.”

What MCP is, in two sentences

Model Context Protocol is a standard for exposing typed tools and resources to LLMs. The Anthropic-stewarded MCP registry has thousands of servers; everything from Stripe to Linear to Supabase ships one, and most modern coding agents speak it natively.

See also