Model Context Protocol (MCP) is easiest to understand as a boundary. On one side is an AI host—Cursor, Junie, Warp, Codex, or another tool. On the other is a server that exposes narrowly described capabilities: read an issue, query a database, inspect a repository, or post a comment. The model chooses a tool; the host asks for approval and executes it; the server talks to the external system.
That boundary is useful, but it is not automatically safe. An MCP server can execute locally, hold credentials, read sensitive data, and perform writes. A good setup therefore optimizes for three things: a small permission surface, reproducible configuration, and visible approval before side effects.
Verified: September 2, 2026 on Apple-silicon macOS. Product behavior changes quickly; use the linked first-party documentation as the final authority.
The three transport choices
stdio: best for one developer on one Mac
The host starts a local command and exchanges protocol messages through standard input and output. Credentials stay in that child process’s environment, there is no listening network port, and process lifetime is handled by the host. For a local Backlog integration, this is the sensible default.
Streamable HTTP: best for an intentionally hosted service
The MCP server listens on a URL. This is useful for teams or remote execution, but it turns local configuration into service operations: TLS, authentication, host/origin validation, logging, uptime, upgrades, and incident response. Nulab explicitly warns not to expose Backlog MCP’s HTTP port to untrusted networks without authentication and TLS.
SSE: compatibility, not the first choice for a new deployment
Some hosts still support the older Server-Sent Events transport. Prefer Streamable HTTP for a new remote server unless the server or host specifically requires SSE.
One server, different host configurations
The inner server entry is intentionally similar across tools:
{
"mcpServers": {
"backlog": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "backlog-mcp-server@0.20.0"],
"env": {
"BACKLOG_DOMAIN": "YOUR-SPACE.backlog.com",
"BACKLOG_API_KEY": "YOUR_BACKLOG_API_KEY",
"ENABLE_TOOLSETS": "space,project,issue"
}
}
}
}
The containing file and lifecycle differ:
| Host | User-wide file | Project file | Current verification surface |
|---|---|---|---|
| Cursor | ~/.cursor/mcp.json | .cursor/mcp.json | Customize → MCPs, or agent mcp list |
| Junie | ~/.junie/mcp/mcp.json | .junie/mcp/mcp.json | IDE MCP Settings or /mcp in Junie CLI |
| Warp | ~/.warp/.mcp.json | .warp/.mcp.json | Settings → Agents → MCP servers |
| Other hosts | Host-specific | Host-specific | Use that host’s first-party docs |
Project configuration is shareable but dangerous if it embeds secrets. It can also cause a cloned repository to propose running a local command. User-wide configuration is less portable but is the better default for a personal API key.
A reusable macOS setup strategy
- Install a supported runtime. The current Backlog MCP package requires Node.js 22 or newer. On an M2 Mac, Homebrew normally installs executables under
/opt/homebrew/bin. - Resolve the real executable. Run
command -v nodeandcommand -v npx. GUI applications do not always inherit the samePATHas an interactive zsh session, so an absolute command path avoids a common “spawn ENOENT” failure. - Pin production tutorials.
backlog-mcp-server@0.20.0makes the behavior repeatable. Periodically test and deliberately update the pin; do not let an unreviewedlatestsilently change every editor at once. - Start read-heavy and narrow. Enable
space,project,issue, keep write calls approval-gated, and add other toolsets only when needed. - Verify identity before data. First call
get_myself, thenget_space, then fetch one known issue. Do not start by creating or updating anything. - Test writes in a sandbox. Add a clearly marked comment to a non-production issue, inspect it in Backlog, and remove or correct it manually if necessary.
Credentials without wishful thinking
The portable JSON example shows the API key inline because every supported host understands it. That does not make it the ideal long-term storage method.
- Prefer a user-scoped config and restrict it with
chmod 600. - Never commit a real key. If a project config needs a placeholder, commit only the placeholder and document local provisioning.
- On Cursor, use supported config interpolation such as
${env:BACKLOG_API_KEY}when the app’s launch environment actually contains that variable. - For a team-hosted HTTP service, use Backlog OAuth so each person authenticates as themselves instead of sharing one API key.
- Keep approval enabled for
add_*,update_*, anddelete_*tools. Treat “auto-run everything” as equivalent to handing the model your account. - Rotate the key if it appears in chat, logs, screenshots, shell history, a commit, or a support bundle.
Backlog rate limits are per user, not per API key. Multiple agents using different keys owned by the same person still share the same allowance. Avoid parallel bulk reads and writes; honor 429 responses and the reset header.
A safe workflow contract
Give the agent explicit phases:
Read Backlog issue DEMO-123 and its comments. Do not modify Backlog or code yet.
Summarize acceptance criteria, ambiguities, and the files likely affected.
Wait for my approval before editing.
After implementation and tests, draft the Backlog comment for my review.
Post it only after I approve the exact text.
The wording matters. It separates retrieval, planning, code changes, and external writes. It also leaves an auditable human decision between each risk boundary.
Troubleshooting across hosts
The server never becomes active. Use the absolute npx path, confirm node --version is 22 or newer, validate the JSON, and run the exact command once in Terminal to allow the package to download.
The server starts and immediately exits. Confirm the domain contains the full hostname but no https:// or path. Check that the API key is active and belongs to a user who can see the target project.
Tools are missing. Inspect ENABLE_TOOLSETS. issue provides issue operations, while project is recommended because other operations often need project metadata.
The model calls the wrong tool. Ask for the exact tool name, reduce enabled toolsets, and state whether the task is read-only. A smaller catalog is easier for a model to use correctly.
Requests suddenly return 429. Stop concurrent agents, wait for the reset time, reduce broad issue searches, and use narrower filters.
会話
最初のコメントを残す