Kontexted MCP CLI

MCP client and proxy for connecting AI assistants to Kontexted.

The Kontexted MCP CLI bridges AI coding assistants (opencode, Claude Code, etc.) with your Kontexted instance. It handles authentication, profile management, and translates MCP requests to your Kontexted server's API.

What is this?

The Kontexted server provides an MCP (Model Context Protocol) endpoint that allows AI assistants to query your notes. Since Kontexted is open source, you can host multiple instances for different teams or environments, and each instance contains multiple workspaces.

This CLI helps you manage these scenarios by:

• OAuth 2.0 Authentication - Handles full OAuth flow with PKCE code verifier
• Profile Management - Store and switch between multiple Kontexted instances and workspaces
• Workspace Scoping - Narrows the LLM's context to a single workspace per profile
• MCP Proxy Server - Translates MCP stdio requests to HTTP calls to Kontexted
• Tool Filtering - Injects workspace context and controls write access per-profile

Installation

Prerequisites

• Kontexted server running at your instance

Using npx / bunx (Recommended)

The easiest way to run Kontexted MCP CLI without installing:

# Using bunx
bunx @kontexted/mcp-cli

# Using npx
npx @kontexted/mcp-cli

No installation required - just replace kontexted-mcp with bunx @kontexted/mcp-cli or npx @kontexted/mcp-cli in all examples below.

Global Install (Optional)

If you prefer a shorter command, install globally:

bun install -g @kontexted/mcp-cli

Then run directly:

kontexted-mcp

Usage

1. Login

Authenticate with your Kontexted instance and store a profile:

kontexted-mcp login --url <mcp-server-url> --workspace <workspace-slug>

Required flags:

• --url: MCP server URL (e.g., http://localhost:3000/api/mcp or https://app.example.com/api/mcp)
• --workspace: Workspace slug from your Kontexted instance

Optional flags:

• --alias <name>: Store profile under a custom name (defaults to workspace name)
• --write: Enable write operations (create folders/notes) for this profile

Examples:

# Login to local development instance
kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project

# Login to production with alias
kontexted-mcp login --url https://app.mycompany.com/api/mcp --workspace my-project --alias prod

# Login with write access enabled
kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project --write

What happens during login:

1. CLI starts a temporary local HTTP server on port 8788
2. Opens your browser to Kontexted's OAuth authorization page
3. You sign in with Keycloak and authorize the MCP client
4. Kontexted redirects to the callback URL with an authorization code
5. CLI exchanges the code for access and refresh tokens
6. Tokens and client information are stored in ~/.kontexted/mcp.json

2. View Stored Profiles

Show all configured profiles:

kontexted-mcp show-config

Output example:

{
  "profiles": {
    "my-project": {
      "serverUrl": "http://localhost:3000/api/mcp",
      "workspace": "my-project",
      "write": false,
      "oauth": {
        "tokens": { "...": "..." },
        "codeVerifier": "...",
        "clientInformation": { "...": "..." }
      }
    },
    "prod": {
      "serverUrl": "https://app.mycompany.com/api/mcp",
      "workspace": "my-project",
      "write": true,
      "oauth": { "...": "..." }
    }
  }
}

3. Start MCP Proxy Server

Run the MCP proxy server (default command when no subcommand is provided):

kontexted-mcp [--alias <name> | --workspace <slug>] [--write | --write-off]

Required flags (one or the other):

• --alias <name>: Use profile by alias
• --workspace <slug>: Find profile by workspace name

Optional flags:

• --write: Override profile to enable write operations
• --write-off: Override profile to disable write operations

Examples:

# Start with default read-only access
kontexted-mcp --alias prod

# Start with write access for this session only
kontexted-mcp --alias my-project --write

# Start using workspace name instead of alias
kontexted-mcp --workspace my-project

The CLI will:

1. Load the specified profile from ~/.kontexted/mcp.json
2. Connect to Kontexted's MCP server using stored tokens
3. List available tools and register them with MCP stdio transport
4. Remove workspaceSlug from tool input schemas (injected automatically)
5. Filter out write tools unless --write is specified
6. Wait for MCP requests from your AI assistant

4. Logout

Remove one or all stored profiles:

# Remove specific profile by alias
kontexted-mcp logout --alias prod

# Remove specific profile by workspace
kontexted-mcp logout --workspace my-project

# Remove all profiles
kontexted-mcp logout

Integrating with opencode

The Kontexted MCP CLI is designed to work as an MCP server that can be configured in opencode.

Step 1: Add MCP Server to opencode.json

Edit your project's opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kontexted": {
      "type": "local",
      "enabled": true,
      "command": ["kontexted-mcp", "--alias", "prod"],
    }
  }
}

Replace --alias with your profile name or use --workspace instead.

Step 2: Configure Write Access (Optional)

If you want opencode to create notes or folders in Kontexted:

1. Enable write access during login: kontexted-mcp login --url <url> --workspace <slug> --write
2. Or override per-session: "args": ["--alias", "prod", "--write"]

Step 3: Restart opencode

Restart your opencode session to load the MCP server.

Step 4: Use Kontexted Tools

opencode can now access Kontexted MCP tools:

• getWorkspaceTree - Fetch workspace structure (folders and notes)
• searchNotesByQuery - Search notes by name or title
• getNoteById - Retrieve a specific note's content
• createFolder - Create a new folder (requires --write)
• createNote - Create a new note (requires --write)

The CLI automatically injects your configured workspaceSlug into all requests, so you don't need to specify it manually.

Tool Filtering

The CLI filters MCP tools based on your profile's write settings:

| Tool | Read-Only | With Write | |-------|------------|------------| | getWorkspaceTree | ✅ | ✅ | | searchNotesByQuery | ✅ | ✅ | | getNoteById | ✅ | ✅ | | createFolder | ❌ | ✅ | | createNote | ❌ | ✅ |

By default, profiles are created in read-only mode. Use --write during login or session start to enable write operations.

Configuration File

Profiles are stored in:

~/.kontexted/mcp.json

Each profile contains:

• serverUrl: Kontexted MCP server URL
• workspace: Workspace slug
• write: Default write access setting
• oauth.tokens: OAuth access and refresh tokens
• oauth.codeVerifier: PKCE code verifier for token refresh
• oauth.clientInformation: OAuth client metadata

Security Note: Tokens are stored in plain text on disk. Ensure your system's ~/.kontexted directory has appropriate permissions.

Troubleshooting

"Unauthorized. Run 'kontexted-mcp login' first."

Your tokens have expired or are missing. Run login again:

kontexted-mcp login --url <url> --workspace <workspace>

The CLI will automatically refresh expired tokens when possible.

"Failed to open browser"

The CLI couldn't automatically open your browser. Copy the URL from your terminal and open it manually.

Port 8788 already in use

The OAuth callback server requires port 8788. If it's occupied:

1. Close other processes using the port, or
2. Manually copy the authorization URL from the CLI output

Profile not found

Check your stored profiles:

kontexted-mcp show-config

Use the exact alias or workspace name shown in the output.

Development

For contributing or running from source code:

# Clone repository
git clone https://github.com/kontexted/kontexted-mcp-cli.git
cd kontexted-mcp-cli

# Install dependencies
bun install

# Run from source
bun run start

# Build distribution
bun run build

Note: Building from source is only necessary for development. For regular use, run with bunx or npx instead.

License

MIT License - Copyright (c) 2026 Rabbyte

Links

• Kontexted Server - Main Kontexted application
• Issues & Bug Reports
• Model Context Protocol - MCP specification