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, strict OAuth 2.1, OAuth 2.0 compatibility
SSE	Server-Sent Events for persistent connections	Real-time data, streaming tools	Headers, strict OAuth 2.1, OAuth 2.0 compatibility

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.1 (MCP 2026-07-28): Strict protected-resource discovery, issuer-bound authorization code with PKCE S256, live refresh, reauthorization, and revocation
• OAuth 2.0: Compatibility mode for older providers

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.1 Authentication

Use strict OAuth 2.1 for a shared MCP connection that implements the current MCP authorization profile:

{
  "name": "web-search",
  "connection_type": "http",
  "connection_string": "https://mcp-server.example.com/mcp",
  "auth_type": "oauth2.1",
  "oauth_config": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "expected_issuer": "https://auth.example.com"
  },
  "tools_to_execute": ["*"]
}

When a client ID is supplied, strict mode treats it as pre-registered and requires its exact expected issuer. When it is empty, DeepIntShield prefers its deployment-owned Client ID Metadata Document (CIMD) if the authorization server advertises support, then uses deprecated RFC 7591 dynamic registration only as the fallback. Authorization, token, registration, and scope fields are optional verification hints in strict mode and must match validated metadata. See registration priority and deployment requirements. Select OAuth 2.0 ("auth_type": "oauth") only for an older compatibility provider.

→ Learn more about OAuth authentication →

Use Cases:

• Shared third-party service authorization and consent
• Third-party service integrations
• Secure credential management
• Strict MCP OAuth 2.1 or older OAuth 2.0 compatibility

This OAuth configuration is shared by calls that use the connection. For a distinct caller credential and resource-bound Streamable HTTP session, use Delegated MCP authentication.

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.1 Authentication

{
  "name": "live-data",
  "connection_type": "sse",
  "connection_string": "https://stream.example.com/mcp/sse",
  "auth_type": "oauth2.1",
  "oauth_config": {
    "client_id": "your-client-id",
    "expected_issuer": "https://auth.example.com"
  },
  "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 Agentic → MCP Registry in the workspace sidebar - the page title is MCP Connections

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 autonomous-execution eligibility 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 are eligible for automatic execution in Agent Mode:

Value	Behavior
["*"]	Every executable tool is eligible for the autonomous loop
[] or omitted	No tools are eligible; calls are returned to the application
["tool1", "tool2"]	Only the named tools are eligible

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.

Eligibility does not replace authorization. When canonical GAF is enabled, the current Virtual-Key binding, governed agent, Registry action, OpenFGA relationships, client configuration, arguments, and any required Command Authority approval must still produce an exact Allow.

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 can contain secrets such as embedded API keys, bearer tokens, and custom authentication headers:

• Stored encrypted at rest when one stable backend DEEPINTSHIELD_ENCRYPTION_KEY is configured
• Redacted in API responses and the Web UI for security
• Resolved automatically during client connection

Without DEEPINTSHIELD_ENCRYPTION_KEY, literal persisted values remain plaintext in the database. Configure the key before storing credentials and do not rotate it without a coordinated data migration. When you create or edit a client in the Web UI, enter the full connection URL or header value directly; DeepIntShield redacts it from later responses and encrypts it when the backend key is enabled. See OAuth encryption and workspace isolation.

---

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 Agentic → MCP Registry 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 Agentic → MCP Registry 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 Agentic → MCP Registry: 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 an eligibility allow-list

Open →