Wire MCP servers into the agent: Linear / Notion / GitHub

Choose the transport deliberately

Start with stdio for local experimentation because the process boundary and logs are easy to inspect. For team deployment, a managed HTTP service can centralize updates and policy, but it also introduces network availability, authentication, and server-side logging concerns.

• stdio starts a local subprocess and communicates over standard input and output. It is the common choice for npm, Python, or company CLI-based servers running on the same machine.
• sse connects to a long-lived remote server using Server-Sent Events. Use it when the provider requires a persistent event stream.
• http uses ordinary HTTP request and response semantics. It fits stateless internal services and centrally operated MCP gateways.

A safer example configuration

MCP servers are configured in <vault>/.kition/mcp.json. Keep secrets out of the JSON file. Reference environment variables or Kition keychain entries so the vault remains safe to back up or commit.

{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${kition:secret:github-mcp-token}"
      }
    },
    "analytics-readonly": {
      "transport": "stdio",
      "command": "uvx",
      "args": [
        "mcp-server-postgres",
        "postgres://reader@localhost:5432/analytics"
      ]
    },
    "internal-tools": {
      "transport": "http",
      "url": "https://mcp.internal.example.com",
      "headers": {
        "Authorization": "Bearer $INTERNAL_MCP_TOKEN"
      }
    }
  }
}

Mount one server at a time

Do not begin by mounting every server you can find. Each server expands the tool surface the model must reason about and adds another dependency with its own credentials, release cycle, and failure modes. Start with one narrow workflow and one narrowly scoped credential.

• For GitHub, begin with read-only repository access before granting issue or pull-request writes.
• For Linear or Jira, limit the token to one workspace or project when the provider supports it.
• For Notion, share only the pages or databases the integration actually needs.
• For databases, use a read-only database role and point it at a replica or analytics schema.
• For internal tools, expose task-specific operations instead of a generic arbitrary HTTP request tool.

Reload and verify discovery

After saving the configuration, restart the agent panel or use Settings → Agent → MCP → Reload. Ask the agent what MCP tools are available and verify that the expected server-prefixed names appear. Discovery proves that the protocol handshake worked; it does not prove the credential has permission to complete a real request.

Run one read-only smoke test, such as listing repositories, fetching a known issue, or querying a harmless table. Confirm the result against the source system. Only then test a write operation, and keep the first write reversible, such as creating a labeled test issue that can be deleted manually.

Apply permissions before normal use

Treat an MCP tool like any other executable capability. Configure allow, ask, or deny rules per server and per operation. A read-only search tool may be safe to allow automatically. Creating an issue, sending a message, updating a document, or executing a deployment should normally ask for confirmation until the workflow has been reviewed.

The credential is also a permission boundary. Agent-side confirmation cannot compensate for an administrator token with access to every repository or production database. Use least-privilege tokens, short expirations where possible, provider-side audit logs, and separate credentials for development and production.

Troubleshoot by layer

• Process startup: if a stdio server never appears, open MCP logs and verify that the command exists in the application environment. Desktop applications often have a different PATH from your terminal, so an absolute command path may be required.
• Protocol handshake: JSON written to stdout by debug logging can corrupt stdio communication. Send diagnostics to stderr and ensure the server version speaks a compatible MCP protocol.
• Authentication: a 401 or 403 usually means the environment or keychain reference did not resolve, the token expired, or the provider scope is too narrow.
• Tool discovery: if the server connects but exposes no tools, inspect whether it provides resources only, requires additional configuration, or failed while loading its capability list.
• Tool execution: validate input arguments and provider-side errors. A discovered tool can still reject a repository name, database query, or unsupported operation.
• Network and TLS: for remote servers, confirm DNS, proxy, certificate trust, and whether the application can reach the endpoint outside your interactive shell.

Production checklist

• Pin or review server package versions instead of silently trusting the latest package on every launch.
• Document the server owner, source repository, transport, scopes, and renewal procedure.
• Store secrets in the OS keychain or a managed environment, never directly in the vault JSON.
• Prefer read-only credentials and explicit write confirmations.
• Set timeouts so a broken remote service does not stall the entire agent task.
• Review MCP logs for sensitive payloads before forwarding them to centralized logging.
• Test server upgrades in a separate vault before rolling them into a team workflow.
• Keep a manual fallback for business-critical actions when the server or upstream API is unavailable.

Where to continue

Use the full MCP server setup documentation for configuration details and the MCP feature overview for the product model. Before granting writes, review Agent permissions and Agent tool calls. Those pages cover the controls that should surround any external integration.