Skip to content

Configuration

Jump to bottom
KubaZ2 edited this page Oct 4, 2026 · 13 revisions

Agent MCP Server is highly customizable. The preferred and most common way to configure it is via a configuration file (such as .ini or .json). You can specify this file when starting the server using the --config parameter (e.g., --config config.ini). This guide will focus on the .ini format. See the JSON Configuration section for details on using a .json file instead.

The configuration is divided into three main sections:

  1. Providers: Your Large Language Model (LLM) backends.
  2. Mcp: Downstream MCP servers you want to connect to.
  3. Agents: The specialized agents exposed to the parent MCP client.

While configuration files are recommended for base setup, you can also override any of these settings dynamically using Environment Variables or CLI arguments. See the Dynamic Configuration Methods section for details.

1. Providers (Providers)

This section defines the connections to your LLM APIs. Because different providers have different capabilities and requirements, the configuration options depend on the Type you specify.

OpenAI Provider

Use this provider for OpenAI or APIs that are OpenAI-compatible (like LMStudio, vLLM, or specific local inference engines).

Option Required Type Description
Type Yes string Must be set to openai.
ApiKey No string The API key for authentication. Can be omitted for local no-auth endpoints.
Endpoint No string The base URL/endpoint for the API (defaults to https://api.openai.com/v1).
TimeoutSeconds No double HTTP client timeout in seconds for LLM requests (defaults to 1024).

Example:

[Providers:my-openai]
Type = openai
ApiKey = sk-your-openai-api-key
TimeoutSeconds = 120

[Providers:local-openai]
Type = openai
Endpoint = http://localhost:1234/v1

Anthropic Provider

Use this provider for Anthropic or APIs that are Anthropic-compatible.

Option Required Type Description
Type Yes string Must be set to anthropic.
ApiKey No string The API key for authentication. Can be omitted for local no-auth endpoints.
Endpoint No string The base URL/endpoint for the API (defaults to https://api.anthropic.com).
TimeoutSeconds No double HTTP client timeout in seconds for LLM requests (defaults to 1024).

Example:

[Providers:claude]
Type = anthropic
ApiKey = sk-your-anthropic-api-key
TimeoutSeconds = 60.5

Ollama Provider

Use this provider for Ollama instances. Ollama supports passing additional dictionary options directly to the model.

Option Required Type Description
Type Yes string Must be set to ollama.
ApiKey No string The API key for authentication. Can be omitted for local no-auth endpoints.
Endpoint No string The URL to your Ollama instance (defaults to http://127.0.0.1:11434).
TimeoutSeconds No double HTTP client timeout in seconds for LLM requests (defaults to 1024).
Options No string, JSON Additional properties sent to Ollama (e.g., temperature, num_ctx). A full reference is available here.

NOTE: The Options field must be a stringified JSON object to preserve strict value types for Ollama. If using a .json configuration file, a nested object will not work. You must use an escaped string:

"Options": "{\"temperature\": 0.7, \"num_ctx\": 16384}"

Example:

[Providers:my-local-ollama]
Type = ollama
TimeoutSeconds = 300
Options = {"temperature": 0.7, "num_ctx": 16384}

2. Downstream MCP Servers (Mcp)

This section defines the connections to other MCP servers. The server automatically detects whether you are configuring a stdio (command-line based) or an http (network based) MCP server based on the presence of the Command or Endpoint property.

Stdio Options (Triggered by Command)

Option Required Type Description
Command Yes string The executable to run (e.g., npx, python, docker).
Args No string[] Array of command-line arguments to pass to the executable.
Env No dict Dictionary of custom environment variables to set.
InheritEnv No bool Whether to inherit the host environment variables (defaults to true).
Cwd No string The working directory where the command will be executed (inherits the current working directory by default).
ShutdownTimeoutSeconds No double How long to wait for the server to gracefully shut down (defaults to 5).
ToolNameFormat No string Format string for the tools exposed to the agent. {0} is the server key, {1} is the tool name (defaults to {0}_{1}).
FailurePolicy No string Policy for handling server startup failures: Skip (default), Fail

Example:

[Mcp:filesystem]
Command = npx
Args:0 = -y
Args:1 = @modelcontextprotocol/server-filesystem
Args:2 = /home/myuser/projects
Env:MY_CUSTOM_VAR = some_value
InheritEnv = true
Cwd = /home/myuser
ShutdownTimeoutSeconds = 5.0
# Prevents prefixing tools with 'filesystem_', keeping their original names
ToolNameFormat = {1}
FailurePolicy = Fail

HTTP Options (Triggered by Endpoint)

Option Required Type Description
Endpoint Yes string The URL endpoint of the HTTP MCP server.
Headers No dict Dictionary of additional HTTP headers to send (e.g., for Authorization).
Mode No string The transport mode: Auto (default), StreamableHttp, or Sse.
SessionId No string A specific session ID to use or resume.
ConnectionTimeoutSeconds No double Connection establishment timeout (defaults to 30).
DefaultReconnectionIntervalSeconds No double Interval between reconnection attempts (defaults to 1).
MaxReconnectionAttempts No int Maximum number of times to try reconnecting (defaults to 5).
OwnsSession No bool Determines if the client owns the session lifecycle (defaults to true).
ToolNameFormat No string Format string for the tools exposed to the agent. {0} is the server key, {1} is the tool name (defaults to {0}_{1}).
FailurePolicy No string Policy for handling server startup failures: Skip (default), Fail

Example:

[Mcp:websearch]
Endpoint = http://localhost:8080/mcp
Headers:Authorization = Bearer my-secret-token
Mode = Sse
SessionId = predefined-session-88
ConnectionTimeoutSeconds = 15.0
DefaultReconnectionIntervalSeconds = 5.0
MaxReconnectionAttempts = 3
OwnsSession = true
ToolNameFormat = {0}-{1}
FailurePolicy = Fail

3. Agents (Agents)

This section defines the AI agents that are dynamically exposed to your parent MCP client via the agent tool.

Option Required Type Description
Provider Yes string The key of a configured provider (from the Providers section).
Model Yes string The LLM model name to use (e.g., qwen3.8:27b, claude-fable-5-1).
Description No string The description of this agent, shown to the parent LLM deciding when to use it.
SystemPrompt No string The core instruction set guiding the agent's behavior.
ToolCallTaskFinishPromptFormat No string Format string injected when an async MCP task finishes. {0} is the Task ID. (defaults to Background task for tool call {0} has finished. Result:\n)
MaxOutputTokens No int Limit for the maximum number of tokens generated by the agent (defaults to no limit).
Mcp No string[] Array of downstream MCP server keys this agent is allowed to access (from the Mcp section).
DefaultToolPolicy No string The default behavior when the agent calls a tool: Ask (default), Allow, or Deny.
AutoApproveTools No string[] List of glob/regex patterns for tools that are automatically approved.
AutoDenyTools No string[] List of glob/regex patterns for tools that are automatically denied.

Note on Regex vs. Glob: In AutoApproveTools and AutoDenyTools, standard strings are treated as globs (e.g., filesystem_read_*). If you wrap the string in forward slashes, it is evaluated as a regular expression (e.g., /^filesystem_read_/).

Example:

[Agents:researcher]
Provider = claude
Model = claude-fable-5-1
Description = Use this agent to search the web and summarize extensive information.
SystemPrompt = You are an expert researcher. Be incredibly thorough and cite sources.
MaxOutputTokens = 8192
Mcp:0 = websearch
# Automatically allow all tools for this agent, no human-in-the-loop asking
DefaultToolPolicy = Allow
# Custom message when a long-running search finishes
ToolCallTaskFinishPromptFormat = The background search with ID {0} is complete. Here are the results:\n

[Agents:coder]
Provider = local-openai
Model = qwen3.8:27b
Description = Use this agent to read and modify local project files.
SystemPrompt = You are a senior developer. Complete the task step by step.
Mcp:0 = filesystem
# By default, Elicitation will ask the user in the UI to approve any action
DefaultToolPolicy = Ask
# Auto-approve safe read operations (using glob and regex)
AutoApproveTools:0 = filesystem_read_*
AutoApproveTools:1 = /^filesystem_list_/
# Strictly forbid moving files, regardless of user prompt
AutoDenyTools:0 = filesystem_move_*

Additional Configuration Options

Logging Configuration

By default, the server logs with the Information level. You can adjust the logging level with a configuration.

# Set the default log level to warning
[Logging:LogLevel]
Default = Warning

# Set the log level for the AgentMcp namespace to debug
[Logging:LogLevel]
AgentMcp = Debug

HTTP Endpoint Configuration

By default, the server listens on http://localhost:5000. You can change this for example with a configuration file or command-line argument.

[Server:Endpoints:Http]
Url = http://0.0.0.0:1234

# Note that you can also define multiple endpoints.
# The Http or MyAwesomeEndpoint section names are arbitrary, but must be unique.
[Server:Endpoints:MyAwesomeEndpoint]
Url = http://localhost:5678

You can also specify the endpoint(s) directly when starting the server. Use a semicolon (;) to separate multiple URLs.

agent-mcp http --config config.ini --urls "http://0.0.0.0:1234;http://localhost:5678"

For more advanced configuration options, please refer to the official Kestrel documentation.

Note: While the official Microsoft documentation uses Kestrel as the root configuration key, Agent MCP Server binds these settings to the Server key. When adapting examples from the official docs, simply replace Kestrel with Server in your configuration file.

Configuration Methods

INI Configuration

The .ini format is the most common and recommended way to configure the server. It is easy to read and write, and supports sections and key-value pairs.

Example:

[Providers:my-local-ollama]
Type = ollama
Options = {"num_ctx": 16384}

[Mcp:filesystem]
Command = npx
Args:0 = -y
Args:1 = @modelcontextprotocol/server-filesystem
Args:2 = /home/myuser/projects

[Agents:researcher]
Provider = my-local-ollama
Model = gemma4:12b
Mcp:0 = filesystem
AutoApproveTools:0 = filesystem_read_*
AutoApproveTools:1 = /^filesystem_list_/

JSON Configuration

While .ini files are generally easier to read and write, you can also use a .json file for configuration. The structure is similar to the .ini format, but uses JSON syntax.

Example:

{
  "Providers": {
    "my-local-ollama": {
      "Type": "ollama",
      "Options": "{\"num_ctx\": 16384}"
    }
  },
  "Mcp": {
    "filesystem": {
      "Command": "npx",
      "Args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/myuser/projects"]
    }
  },
  "Agents": {
    "researcher": {
      "Provider": "my-local-ollama",
      "Model": "gemma4:12b",
      "Mcp": ["filesystem"],
      "AutoApproveTools": ["filesystem_read_*", "/^filesystem_list_/"]
    }
  }
}

Dynamic Configuration Methods

While an .ini or .json file is great for defining your baseline topology (providers, servers, and agents), you might not want to hardcode sensitive information like API keys, or you may need to override specific settings in different environments.

You can easily mix and match configuration methods. The server will merge them together, allowing you to use a config file for static routing and dynamic inputs for secrets.

Environment Variables

You can override or set any configuration value using environment variables. Because environment variables don't naturally support nested structures, use a double underscore (__) to traverse the hierarchy defined in the sections above.

For example, to securely set the ApiKey for the Anthropic provider named claude without putting it in your config file:

export Providers__claude__ApiKey="sk-your-anthropic-api-key"

To dynamically add an item to an array (like the AutoApproveTools list for an agent named coder), use the array index number:

export Agents__coder__AutoApproveTools__0="filesystem_read_*"

Command Line Arguments

Similarly, you can pass individual settings directly when running the server. Use a colon (:) to define the configuration hierarchy on the fly.

agent-mcp --config config.ini --Providers:my-openai:ApiKey "sk-your-openai-api-key"

Clone this wiki locally