Connect CSC to tools via MCP

Learn how to connect CSC to your tools with the Model Context Protocol.

CSC can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP), an open source standard for AI-tool integrations. MCP servers give CSC access to your tools, databases, and APIs.

Connect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, CSC can read and act on that system directly instead of working from what you paste.

What you can do with MCP

With MCP servers connected, you can ask CSC to:

• Implement features from issue trackers: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
• Analyze monitoring data: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
• Query databases: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
• Integrate designs: "Update our standard email template based on the new Figma designs that were posted in Slack"
• Automate workflows: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."
• React to external events: An MCP server can also act as a channel that pushes messages into your session, so CSC can react to Telegram messages, Discord chats, or webhook events while you're away.

Popular MCP servers

Here are some commonly used MCP servers you can connect to CSC:

⚠️ Warning: Use third party MCP servers at your own risk - CoStrict has not verified the correctness or security of all these servers. Make sure you trust MCP servers you are installing. Be especially careful when using MCP servers that could fetch untrusted content, as these can expose you to prompt injection risk.

Note: Need a specific integration? Find hundreds of MCP servers on GitHub, or build your own using the MCP SDK.

Installing MCP servers

MCP servers can be configured in three different ways depending on your needs:

Option 1: Add a remote HTTP server

HTTP servers are the recommended option for connecting to remote MCP servers. This is the most widely supported transport for cloud-based services.

# Basic syntax
csc mcp add --transport http <name> <url>

# Real example: Connect to Notion
csc mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
csc mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Option 2: Add a remote SSE server

⚠️ Warning: The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.

# Basic syntax
csc mcp add --transport sse <name> <url>

# Real example: Connect to Asana
csc mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
csc mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Add a local stdio server

Stdio servers run as local processes on your machine. They're ideal for tools that need direct system access or custom scripts.

# Basic syntax
csc mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
csc mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Note: Important: Option ordering

All options (--transport, --env, --scope, --header) must come before the server name. The -- (double dash) then separates the server name from the command and arguments that get passed to the MCP server.

For example:

• csc mcp add --transport stdio myserver -- npx server → runs npx server
• csc mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → runs python server.py --port 8080 with KEY=value in environment

This prevents conflicts between CSC's flags and the server's flags.

Managing your servers

Once configured, you can manage your MCP servers with these commands:

# List all configured servers
csc mcp list

# Get details for a specific server
csc mcp get github

# Remove a server
csc mcp remove github

# (within CSC) Check server status
/mcp

Dynamic tool updates

CSC supports MCP list_changed notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a list_changed notification, CSC automatically refreshes the available capabilities from that server.

Push messages with channels

An MCP server can also push messages directly into your session so CSC can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the claude/channel capability and you opt it in with the --channels flag at startup. See Channels to use an officially supported channel, or see Channels reference to build your own.

Tip:

• Use the --scope flag to specify where the configuration is stored:
  • local (default): Available only to you in the current project (was called project in older versions)
  • project: Shared with everyone in the project via .mcp.json file
  • user: Available to you across all projects (was called global in older versions)
• Set environment variables with --env flags (for example, --env KEY=value)
• Configure MCP server startup timeout using the MCP_TIMEOUT environment variable (for example, MCP_TIMEOUT=10000 csc sets a 10-second timeout)
• CSC will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the MAX_MCP_OUTPUT_TOKENS environment variable (for example, MAX_MCP_OUTPUT_TOKENS=50000)
• Use /mcp to authenticate with remote servers that require OAuth 2.0 authentication

⚠️ Warning: Windows Users: On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper to ensure proper execution.

# This creates command="cmd" which Windows can execute
csc mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Without the cmd /c wrapper, you'll encounter "Connection closed" errors because Windows cannot directly execute npx. (See the note above for an explanation of the -- parameter.)

Plugin-provided MCP servers

Plugins can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers.

How plugin MCP servers work:

• Plugins define MCP servers in .mcp.json at the plugin root or inline in plugin.json
• When a plugin is enabled, its MCP servers start automatically
• Plugin MCP tools appear alongside manually configured MCP tools
• Plugin servers are managed through plugin installation (not /mcp commands)

Example plugin MCP configuration:

In .mcp.json at plugin root:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Or inline in plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Plugin MCP features:

• Automatic lifecycle: At session startup, servers for enabled plugins connect automatically. If you enable or disable a plugin during a session, run /reload-plugins to connect or disconnect its MCP servers
• Environment variables: use ${CLAUDE_PLUGIN_ROOT} for bundled plugin files and ${CLAUDE_PLUGIN_DATA} for persistent state that survives plugin updates
• User environment access: Access to same environment variables as manually configured servers
• Multiple transport types: Support stdio, SSE, and HTTP transports (transport support may vary by server)

Viewing plugin MCP servers:

# Within CSC, see all MCP servers including plugin ones
/mcp

Plugin servers appear in the list with indicators showing they come from plugins.

Benefits of plugin MCP servers:

• Bundled distribution: Tools and servers packaged together
• Automatic setup: No manual MCP configuration needed
• Team consistency: Everyone gets the same tools when plugin is installed

See the plugin components reference for details on bundling MCP servers with plugins.

MCP installation scopes

MCP servers can be configured at three scopes. The scope you choose controls which projects the server loads in and whether the configuration is shared with your team.

Scope	Loads in	Shared with team	Stored in
Local	Current project only	No	~/.costrict.json
Project	Current project only	Yes, via version control	.mcp.json in project root
User	All your projects	No	~/.costrict.json

Local scope

Local scope is the default. A local-scoped server loads only in the project where you added it and stays private to you. CSC stores it in ~/.costrict.json under that project's path, so the same server won't appear in your other projects. Use local scope for personal development servers, experimental configurations, or servers with credentials you don't want in version control.

Note: The term "local scope" for MCP servers differs from general local settings. MCP local-scoped servers are stored in ~/.costrict.json (your home directory), while general local settings use .costrict/settings.local.json (in the project directory). See Settings for details on settings file locations.

# Add a local-scoped server (default)
csc mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
csc mcp add --transport http stripe --scope local https://mcp.stripe.com

The command writes the server into the entry for your current project inside ~/.costrict.json. The example below shows the result when you run it from /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Project scope

Project-scoped servers enable team collaboration by storing configurations in a .mcp.json file at your project's root directory. This file is designed to be checked into version control, ensuring all team members have access to the same MCP tools and services. When you add a project-scoped server, CSC automatically creates or updates this file with the appropriate configuration structure.

# Add a project-scoped server
csc mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

The resulting .mcp.json file follows a standardized format:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

For security reasons, CSC prompts for approval before using project-scoped servers from .mcp.json files. If you need to reset these approval choices, use the csc mcp reset-project-choices command.

User scope

User-scoped servers are stored in ~/.costrict.json and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.

# Add a user server
csc mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Scope hierarchy and precedence

When the same server is defined in more than one place, CSC connects to it once, using the definition from the highest-precedence source:

1. Local scope
2. Project scope
3. User scope
4. Plugin-provided servers
5. costrict.ai connectors

The three scopes match duplicates by name. Plugins and connectors match by endpoint, so one that points at the same URL or command as a server above is treated as a duplicate.

Environment variable expansion in .mcp.json

CSC supports environment variable expansion in .mcp.json files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.

Supported syntax:

• ${VAR} - Expands to the value of environment variable VAR
• ${VAR:-default} - Expands to VAR if set, otherwise uses default

Expansion locations: Environment variables can be expanded in:

• command - The server executable path
• args - Command-line arguments
• env - Environment variables passed to the server
• url - For HTTP server types
• headers - For HTTP server authentication

Example with variable expansion:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

If a required environment variable is not set and has no default value, CSC will fail to parse the config.

Practical examples

Example: Monitor errors with Sentry

csc mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authenticate with your Sentry account:

/mcp

Then debug production issues:

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

Example: Connect to GitHub for code reviews

csc mcp add --transport http github https://api.githubcopilot.com/mcp/

Authenticate if needed by selecting "Authenticate" for GitHub:

/mcp

Then work with GitHub:

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

Example: Query your PostgreSQL database

csc mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Then query your database naturally:

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

Authenticate with remote MCP servers

Many cloud-based MCP servers require authentication. CSC supports OAuth 2.0 for secure connections.

Step 1: Add the server that requires authentication

For example:

csc mcp add --transport http sentry https://mcp.sentry.dev/mcp

Step 2: Use the /mcp command within CSC

In CSC, use the command:

/mcp

Then follow the steps in your browser to login.

Tip:

• Authentication tokens are stored securely and refreshed automatically
• Use "Clear authentication" in the /mcp menu to revoke access
• If your browser doesn't open automatically, copy the provided URL and open it manually
• If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in CSC
• OAuth authentication works with HTTP servers

Use a fixed OAuth callback port

Some MCP servers require a specific redirect URI registered in advance. By default, CSC picks a random available port for the OAuth callback. Use --callback-port to fix the port so it matches a pre-registered redirect URI of the form http://localhost:PORT/callback.

You can use --callback-port on its own (with dynamic client registration) or together with --client-id (with pre-configured credentials).

# Fixed callback port with dynamic client registration
csc mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Use pre-configured OAuth credentials

Some MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like "Incompatible auth server: does not support dynamic client registration," the server requires pre-configured credentials. CSC also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server.

Step 1: Register an OAuth app with the server

Create an app through the server's developer portal and note your client ID and client secret.

Many servers also require a redirect URI. If so, choose a port and register a redirect URI in the format http://localhost:PORT/callback. Use that same port with --callback-port in the next step.

Step 2: Add the server with your credentials

Choose one of the following methods. The port used for --callback-port can be any available port. It just needs to match the redirect URI you registered in the previous step.

csc mcp add

Use --client-id to pass your app's client ID. The --client-secret flag prompts for the secret with masked input:

csc mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

csc mcp add-json

Include the oauth object in the JSON config and pass --client-secret as a separate flag:

csc mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

csc mcp add-json (callback port only)

Use --callback-port without a client ID to fix the port while using dynamic client registration:

csc mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

CI / env var

Set the secret via environment variable to skip the interactive prompt:

MCP_CLIENT_SECRET=your-secret csc mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Step 3: Authenticate in CSC

Run /mcp in CSC and follow the browser login flow.

Tip:

• The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config
• If the server uses a public OAuth client with no secret, use only --client-id without --client-secret
• --callback-port can be used with or without --client-id
• These flags only apply to HTTP and SSE transports. They have no effect on stdio servers
• Use csc mcp get <name> to verify that OAuth credentials are configured for a server

Override OAuth metadata discovery

If your MCP server's standard OAuth metadata endpoints return errors but the server exposes a working OIDC endpoint, you can point CSC at a specific metadata URL to bypass the default discovery chain. By default, CSC first checks RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource, then falls back to RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server.

Set authServerMetadataUrl in the oauth object of your server's config in .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

The URL must use https://. This option requires CSC v2.1.64 or later.

Use dynamic headers for custom authentication

If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use headersHelper to generate request headers at connection time. CSC runs the command and merges its output into the connection headers.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

The command can also be inline:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Requirements:

• The command must write a JSON object of string key-value pairs to stdout
• The command runs in a shell with a 10-second timeout
• Dynamic headers override any static headers with the same name

The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.

CSC sets these environment variables when executing the helper:

Variable	Value
CLAUDE_CODE_MCP_SERVER_NAME	the name of the MCP server
CLAUDE_CODE_MCP_SERVER_URL	the URL of the MCP server

Use these to write a single helper script that serves multiple MCP servers.

Note: headersHelper executes arbitrary shell commands. When defined at project or local scope, it only runs after you accept the workspace trust dialog.

Add MCP servers from JSON configuration

If you have a JSON configuration for an MCP server, you can add it directly:

Step 1: Add an MCP server from JSON

# Basic syntax
csc mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
csc mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
csc mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
csc mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Step 2: Verify the server was added

csc mcp get weather-api

Tip:

• Make sure the JSON is properly escaped in your shell
• The JSON must conform to the MCP server configuration schema
• You can use --scope user to add the server to your user configuration instead of the project-specific one

Use CSC as an MCP server

You can use CSC itself as an MCP server that other applications can connect to:

# Start CSC as a stdio MCP server
csc mcp serve

You can use this in Claude Desktop by adding this configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "csc",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

⚠️ Warning: Configuring the executable path: The command field must reference the CSC executable. If the csc command is not in your system's PATH, you'll need to specify the full path to the executable.

To find the full path:

which csc

Then use the full path in your configuration:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/csc",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Without the correct executable path, you'll encounter errors like spawn csc ENOENT.

Tip:

• The server provides access to CSC's tools like View, Edit, LS, etc.
• In Claude Desktop, try asking CSC to read files in a directory, make edits, and more.
• Note that this MCP server is only exposing CSC's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.

MCP output limits and warnings

When MCP tools produce large outputs, CSC helps manage the token usage to prevent overwhelming your conversation context:

• Output warning threshold: CSC displays a warning when any MCP tool output exceeds 10,000 tokens
• Configurable limit: you can adjust the maximum allowed MCP output tokens using the MAX_MCP_OUTPUT_TOKENS environment variable
• Default limit: the default maximum is 25,000 tokens
• Scope: the environment variable applies to tools that don't declare their own limit. Tools that set anthropic/maxResultSizeChars use that value instead for text content, regardless of what MAX_MCP_OUTPUT_TOKENS is set to. Tools that return image data are still subject to MAX_MCP_OUTPUT_TOKENS

To increase the limit for tools that produce large outputs:

export MAX_MCP_OUTPUT_TOKENS=50000
csc

This is particularly useful when working with MCP servers that:

• Query large datasets or databases
• Generate detailed reports or documentation
• Process extensive log files or debugging information

Raise the limit for a specific tool

If you're building an MCP server, you can allow individual tools to return results larger than the default persist-to-disk threshold by setting _meta["anthropic/maxResultSizeChars"] in the tool's tools/list response entry. CSC raises that tool's threshold to the annotated value, up to a hard ceiling of 500,000 characters.

This is useful for tools that return inherently large but necessary outputs, such as database schemas or full file trees. Without the annotation, results that exceed the default threshold are persisted to disk and replaced with a file reference in the conversation.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

The annotation applies independently of MAX_MCP_OUTPUT_TOKENS for text content, so users don't need to raise the environment variable for tools that declare it. Tools that return image data are still subject to the token limit.

⚠️ Warning: If you frequently encounter output warnings with specific MCP servers you don't control, consider increasing the MAX_MCP_OUTPUT_TOKENS limit. You can also ask the server author to add the anthropic/maxResultSizeChars annotation or to paginate their responses. The annotation has no effect on tools that return image content; for those, raising MAX_MCP_OUTPUT_TOKENS is the only option.

Respond to MCP elicitation requests

MCP servers can request structured input from you mid-task using elicitation. When a server needs information it can't get on its own, CSC displays an interactive dialog and passes your response back to the server. No configuration is required on your side: elicitation dialogs appear automatically when a server requests them.

Servers can request input in two ways:

• Form mode: CSC shows a dialog with form fields defined by the server (for example, a username and password prompt). Fill in the fields and submit.
• URL mode: CSC opens a browser URL for authentication or approval. Complete the flow in the browser, then confirm in the CLI.

To auto-respond to elicitation requests without showing a dialog, use Elicitation Hooks.

If you're building an MCP server that uses elicitation, see the MCP elicitation specification for protocol details and schema examples.

Use MCP resources

MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.

Reference MCP resources

Step 1: List available resources

Type @ in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu.

Step 2: Reference a specific resource

Use the format @server:protocol://resource/path to reference a resource:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Step 3: Multiple resource references

You can reference multiple resources in a single prompt:

Compare @postgres:schema://users with @docs:file://database/user-model

Tip:

• Resources are automatically fetched and included as attachments when referenced
• Resource paths are fuzzy-searchable in the @ mention autocomplete
• CSC automatically provides tools to list and read MCP resources when servers support them
• Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)

Scale with MCP Tool Search

Tool search keeps MCP context usage low by deferring tool definitions until CSC needs them. Only tool names load at session start, so adding more MCP servers has minimal impact on your context window.

How it works

Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and CSC uses a search tool to discover relevant ones when a task needs them. Only the tools CSC actually uses enter context. From your perspective, MCP tools work exactly as before.

If you prefer threshold-based loading, set ENABLE_TOOL_SEARCH=auto to load schemas upfront when they fit within 10% of the context window and defer only the overflow. See Configure tool search for all options.

For MCP server authors

If you're building an MCP server, the server instructions field becomes more useful with Tool Search enabled. Server instructions help CSC understand when to search for your tools, similar to how Skills work.

Add clear, descriptive server instructions that explain:

• What category of tasks your tools handle
• When CSC should search for your tools
• Key capabilities your server provides

CSC truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.

Configure tool search

Tool search is enabled by default: MCP tools are deferred and discovered on demand. When ANTHROPIC_BASE_URL points to a non-first-party host, tool search is disabled by default because most proxies do not forward tool_reference blocks. Set ENABLE_TOOL_SEARCH explicitly if your proxy does. This feature requires models that support tool_reference blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.

Control tool search behavior with the ENABLE_TOOL_SEARCH environment variable:

Value	Behavior
(unset)	All MCP tools deferred and loaded on demand. Falls back to loading upfront when ANTHROPIC_BASE_URL is a non-first-party host
true	All MCP tools deferred, including for non-first-party ANTHROPIC_BASE_URL
auto	Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise
auto:<N>	Threshold mode with a custom percentage, where <N> is 0-100 (e.g., auto:5 for 5%)
false	All MCP tools loaded upfront, no deferral

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 csc

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false csc

Or set the value in your settings.json env field.

You can also disable the ToolSearch tool specifically:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Use MCP prompts as commands

MCP servers can expose prompts that become available as commands in CSC.

Execute MCP prompts

Step 1: Discover available prompts

Type / to see all available commands, including those from MCP servers. MCP prompts appear with the format /mcp__servername__promptname.

Step 2: Execute a prompt without arguments

/mcp__github__list_prs

Step 3: Execute a prompt with arguments

Many prompts accept arguments. Pass them space-separated after the command:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

Tip:

• MCP prompts are dynamically discovered from connected servers
• Arguments are parsed based on the prompt's defined parameters
• Prompt results are injected directly into the conversation
• Server and prompt names are normalized (spaces become underscores)

Managed MCP configuration

For organizations that need centralized control over MCP servers, CSC supports two configuration options:

1. Exclusive control with managed-mcp.json: Deploy a fixed set of MCP servers that users cannot modify or extend
2. Policy-based control with allowlists/denylists: Allow users to add their own servers, but restrict which ones are permitted

These options allow IT administrators to:

• Control which MCP servers employees can access: Deploy a standardized set of approved MCP servers across the organization
• Prevent unauthorized MCP servers: Restrict users from adding unapproved MCP servers
• Disable MCP entirely: Remove MCP functionality completely if needed

Option 1: Exclusive control with managed-mcp.json

When you deploy a managed-mcp.json file, it takes exclusive control over all MCP servers. Users cannot add, modify, or use any MCP servers other than those defined in this file. This is the simplest approach for organizations that want complete control.

System administrators deploy the configuration file to a system-wide directory:

• macOS: /Library/Application Support/CoStrict/managed-mcp.json
• Linux and WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\CoStrict\managed-mcp.json

Note: These are system-wide paths (not user home directories like ~/Library/...) that require administrator privileges. They are designed to be deployed by IT administrators.

The managed-mcp.json file uses the same format as a standard .mcp.json file:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Option 2: Policy-based control with allowlists and denylists

Instead of taking exclusive control, administrators can allow users to configure their own MCP servers while enforcing restrictions on which servers are permitted. This approach uses allowedMcpServers and deniedMcpServers in the managed settings file.

Note: Choosing between options: Use Option 1 (managed-mcp.json) when you want to deploy a fixed set of servers with no user customization. Use Option 2 (allowlists/denylists) when you want to allow users to add their own servers within policy constraints.

Restriction options

Each entry in the allowlist or denylist can restrict servers in three ways:

1. By server name (serverName): Matches the configured name of the server
2. By command (serverCommand): Matches the exact command and arguments used to start stdio servers
3. By URL pattern (serverUrl): Matches remote server URLs with wildcard support

Important: Each entry must have exactly one of serverName, serverCommand, or serverUrl.

Example configuration

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

How command-based restrictions work

Exact matching:

• Command arrays must match exactly - both the command and all arguments in the correct order
• Example: ["npx", "-y", "server"] will NOT match ["npx", "server"] or ["npx", "-y", "server", "--flag"]

Stdio server behavior:

• When the allowlist contains any serverCommand entries, stdio servers must match one of those commands
• Stdio servers cannot pass by name alone when command restrictions are present
• This ensures administrators can enforce which commands are allowed to run

Non-stdio server behavior:

• Remote servers (HTTP, SSE, WebSocket) use URL-based matching when serverUrl entries exist in the allowlist
• If no URL entries exist, remote servers fall back to name-based matching
• Command restrictions do not apply to remote servers

How URL-based restrictions work

URL patterns support wildcards using * to match any sequence of characters. This is useful for allowing entire domains or subdomains.

Wildcard examples:

• https://mcp.company.com/* - Allow all paths on a specific domain
• https://*.example.com/* - Allow any subdomain of example.com
• http://localhost:*/* - Allow any port on localhost

Remote server behavior:

• When the allowlist contains any serverUrl entries, remote servers must match one of those URL patterns
• Remote servers cannot pass by name alone when URL restrictions are present
• This ensures administrators can enforce which remote endpoints are allowed

Example: URL-only allowlist

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

Result:

• HTTP server at https://mcp.company.com/api: ✅ Allowed (matches URL pattern)
• HTTP server at https://api.internal.corp/mcp: ✅ Allowed (matches wildcard subdomain)
• HTTP server at https://external.com/mcp: ❌ Blocked (doesn't match any URL pattern)
• Stdio server with any command: ❌ Blocked (no name or command entries to match)

Example: Command-only allowlist

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

Result:

• Stdio server with ["npx", "-y", "approved-package"]: ✅ Allowed (matches command)
• Stdio server with ["node", "server.js"]: ❌ Blocked (doesn't match command)
• HTTP server named "my-api": ❌ Blocked (no name entries to match)

Example: Mixed name and command allowlist

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

Result:

• Stdio server named "local-tool" with ["npx", "-y", "approved-package"]: ✅ Allowed (matches command)
• Stdio server named "local-tool" with ["node", "server.js"]: ❌ Blocked (command entries exist but doesn't match)
• Stdio server named "github" with ["node", "server.js"]: ❌ Blocked (stdio servers must match commands when command entries exist)
• HTTP server named "github": ✅ Allowed (matches name)
• HTTP server named "other-api": ❌ Blocked (name doesn't match)

Example: Name-only allowlist

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

Result:

• Stdio server named "github" with any command: ✅ Allowed (no command restrictions)
• Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)
• HTTP server named "github": ✅ Allowed (matches name)
• Any server named "other": ❌ Blocked (name doesn't match)

Allowlist behavior (allowedMcpServers)

• undefined (default): No restrictions - users can configure any MCP server
• Empty array []: Complete lockdown - users cannot configure any MCP servers
• List of entries: Users can only configure servers that match by name, command, or URL pattern

Denylist behavior (deniedMcpServers)

• undefined (default): No servers are blocked
• Empty array []: No servers are blocked
• List of entries: Specified servers are explicitly blocked across all scopes

Important notes

• Option 1 and Option 2 can be combined: If managed-mcp.json exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the managed servers themselves.
• Denylist takes absolute precedence: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist
• Name-based, command-based, and URL-based restrictions work together: a server passes if it matches either a name entry, a command entry, or a URL pattern (unless blocked by denylist)

Note: When using managed-mcp.json: Users cannot add MCP servers through csc mcp add or configuration files. The allowedMcpServers and deniedMcpServers settings still apply to filter which managed servers are actually loaded.