Connecting to MCP Servers

Overview

DeepIntShield can connect to any MCP-compatible server to discover and execute tools. Each connection is called an MCP Client in DeepIntShield terminology.

Connection Types

DeepIntShield supports three connection protocols, each with different authentication options:

Type	Description	Best For	Auth Support
STDIO	Spawns a subprocess and communicates via stdin/stdout	Local tools, CLI utilities, scripts	None
HTTP	Sends requests to an HTTP endpoint	Remote APIs, microservices, cloud functions	Headers, OAuth 2.0
SSE	Server-Sent Events for persistent connections	Real-time data, streaming tools	Headers, OAuth 2.0

STDIO Connections

STDIO connections launch external processes and communicate via standard input/output. Best for local tools and scripts.

{
  "name": "filesystem",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-filesystem"],
    "envs": ["HOME", "PATH"]
  },
  "tools_to_execute": ["*"]
}

Use Cases:

• Local filesystem operations
• Python/Node.js MCP servers
• CLI utilities and scripts
• Database tools with local credentials

Caution

Docker Users: When running DeepIntShield in Docker, STDIO connections may not work if the required commands (e.g., npx, python) are not installed in the container. For STDIO-based MCP servers, build a custom Docker image that includes the necessary dependencies, or use HTTP/SSE connections to externally hosted MCP servers.

HTTP Connections

HTTP connections communicate with MCP servers via HTTP requests. Ideal for remote services and microservices.

HTTP connections support two authentication methods:

• Header-based authentication: Static headers (API keys, custom tokens)
• OAuth 2.0: Dynamic token-based authentication with automatic token refresh

Header-Based Authentication

Use static headers for API keys and custom authentication tokens:

{
  "name": "web-search",
  "connection_type": "http",
  "connection_string": "https://mcp-server.example.com/mcp",
  "auth_type": "headers",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "X-Custom-Header": "value"
  },
  "tools_to_execute": ["*"]
}

Use Cases:

• Static API keys
• Bearer token authentication
• Custom header-based auth schemes

OAuth 2.0 Authentication

Use OAuth 2.0 for secure, user-based authentication with automatic token refresh:

{
  "name": "web-search",
  "connection_type": "http",
  "connection_string": "https://mcp-server.example.com/mcp",
  "auth_type": "oauth",
  "oauth_config": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "authorize_url": "https://auth.example.com/authorize",
    "token_url": "https://auth.example.com/token",
    "scopes": ["read", "write"]
  },
  "tools_to_execute": ["*"]
}

Features:

• Automatic token refresh before expiration
• PKCE support for public clients
• Dynamic client registration (RFC 7591)
• OAuth discovery from server URLs

→ Learn more about OAuth authentication →

Use Cases:

• User-delegated access
• Third-party service integrations
• Secure credential management
• Compliance with OAuth 2.0 standards

Overall HTTP Use Cases:

• Remote API integrations
• Cloud-hosted MCP services
• Microservice architectures
• Third-party tool providers

SSE Connections

Server-Sent Events (SSE) connections provide real-time, persistent connections to MCP servers. Like HTTP connections, SSE supports both header-based and OAuth authentication.

Header-Based Authentication

{
  "name": "live-data",
  "connection_type": "sse",
  "connection_string": "https://stream.example.com/mcp/sse",
  "auth_type": "headers",
  "headers": {
    "Authorization": "Bearer your-api-key"
  },
  "tools_to_execute": ["*"]
}

OAuth 2.0 Authentication

{
  "name": "live-data",
  "connection_type": "sse",
  "connection_string": "https://stream.example.com/mcp/sse",
  "auth_type": "oauth",
  "oauth_config": {
    "client_id": "your-client-id",
    "authorize_url": "https://auth.example.com/authorize",
    "token_url": "https://auth.example.com/token",
    "scopes": ["stream:read"]
  },
  "tools_to_execute": ["*"]
}

Use Cases:

• Real-time market data
• Live system monitoring
• Event-driven workflows
• User-authenticated streaming connections

→ Learn more about OAuth authentication →

---

Gateway Setup

Adding an MCP Client

1. Navigate to MCP Gateway in the sidebar - you’ll see a table of all registered servers

2. Click New MCP Server button to open the creation form

3. Fill in the connection details:

Fields:

• Name: Unique identifier (no spaces or hyphens, ASCII only)
• Connection Type: STDIO, HTTP, or SSE
• For STDIO: Command, arguments, and environment variables
• For HTTP/SSE: Connection URL

4. Click Create to connect

Viewing and Managing Connected Tools

Once connected, click on any client row to open the configuration sheet:

Here you can:

• View all discovered tools with their descriptions and parameters
• Enable/disable individual tools via toggle switches
• Configure auto-execution for specific tools
• Edit custom headers for HTTP/SSE connections
• View the full connection configuration as JSON

---

Tool Field Semantics

tools_to_execute

Controls which tools from the client are available:

Value	Behavior
["*"]	All tools from this client are included
[] or omitted	No tools included (deny-by-default)
["tool1", "tool2"]	Only specified tools are included

tools_to_auto_execute (Agent Mode)

Controls which tools can be automatically executed in Agent Mode:

Value	Behavior
["*"]	All tools are auto-executed
[] or omitted	No tools are auto-executed (manual approval required)
["tool1", "tool2"]	Only specified tools are auto-executed

Note

A tool must be in both tools_to_execute and tools_to_auto_execute to be auto-executed. If a tool is in tools_to_auto_execute but not in tools_to_execute, it will be skipped.

Example configuration:

{
  "name": "filesystem",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-filesystem"]
  },
  "tools_to_execute": ["*"],
  "tools_to_auto_execute": ["read_file", "list_directory"]
}

---

Sensitive Connection Values

Connection strings and headers that contain secrets (URLs with embedded API keys, bearer tokens, custom auth headers) are handled securely:

• Stored encrypted at rest
• Redacted in API responses and the Web UI for security
• Resolved automatically during client connection

When you create or edit a client in the Web UI, enter the full connection URL or header value directly - DeepIntShield encrypts and redacts it for you.

---

Client State Management

Connection States

State	Description
connected	Client is active and tools are available
connecting	Client is establishing connection
disconnected	Client lost connection but can be reconnected
error	Client configuration or connection failed

Managing Clients at Runtime

Manage connected clients from the MCP Gateway in the Web UI:

• Reconnect a client: open the client row and click Reconnect to re-establish the connection.
• Edit client configuration: open the client’s configuration sheet to change the connection details, headers, or the set of tools in tools_to_execute, then click Save Changes.
• Remove a client: open the client row and delete it to disconnect and remove it from the gateway.

---

Health Monitoring

DeepIntShield automatically monitors MCP client health with periodic checks every 10 seconds by default.

Health Check Methods

By default, DeepIntShield uses the lightweight ping method for health checks. However, you can configure the health check method based on your MCP server’s capabilities:

Method	When to Use	Overhead	Fallback
Ping (default)	Server supports MCP ping protocol	Minimal	Best for most servers
ListTools	Server doesn’t support ping, or you need heavier checks	Higher	More resource-intensive

Configuring Health Check Method

You can toggle the is_ping_available setting for each client from the Web UI:

1. Navigate to MCP Gateway and select a server
2. In the configuration panel, toggle “Ping Available for Health Check”
3. Enable: Uses lightweight ping for health checks
4. Disable: Uses listTools method for health checks instead

Health Check Behavior

When a client disconnects:

1. State changes to disconnected
2. Tools from that client become unavailable
3. You can reconnect from the Web UI

Note: Changing is_ping_available takes effect immediately without requiring a client reconnection.

---

Connection Resilience

A brief network hiccup won’t take your tools offline: DeepIntShield retries transient connection failures with exponential backoff (a few attempts over roughly 30 seconds) and automatically reconnects a client in the background once its health checks fail. You don’t need to configure anything for this to work.

What this means for you when debugging a connection:

• Transient failures resolve on their own. Connection timeouts, refused connections, DNS hiccups, HTTP 5xx, and HTTP 429 are retried automatically - a client may briefly show connecting and recover without intervention.
• Configuration mistakes fail fast. Auth failures (401/403), bad requests (400/405/422), invalid credentials, and a missing command (e.g. command not found: npx) are not retried. If a client lands in the error state immediately, check the connection URL, credentials/headers, and - for STDIO - that the command exists in the runtime environment.
• Disconnected clients reconnect automatically. After repeated health-check failures a client is marked disconnected, its tools become unavailable, and DeepIntShield reconnects it in the background. Tools return automatically once it recovers.

Manual Reconnection

You can also trigger a reconnection yourself at any time from the MCP Gateway: open the client row and click Reconnect. Manual reconnection also uses the retry logic for robustness.

---

Naming Conventions

MCP client names have specific requirements:

Caution

• Must contain only ASCII characters
• Cannot contain hyphens (-) or spaces
• Cannot start with a number
• Must be unique across all clients

Valid names: filesystem, web_search, myAPI, tool123

Invalid names: my-tools, web search, 123tools, datos-api

---

Next Steps

Tool Execution

Learn how to execute tools from connected MCP servers

Open →

Agent Mode

Enable autonomous tool execution with auto-approval

Open →