Providers Guide

New to Axiolex? Start with the overview or the quick start guide.

This guide explains how to configure MCP and A2A providers for Axiolex and how to discover their tools into the searchable tool catalog.

Providers are external capability sources — MCP servers (Model Context Protocol) or A2A agents (Agent-to-Agent). Axiolex stores provider connection details in source_files/mcp_providers.yaml, discovers tools/skills from enabled providers, normalizes them, and caches searchable discovery/runtime metadata for retrieval and execution workflows. The caller never needs to know which protocol backs a tool — Axiolex resolves the transport, endpoint, and credentials server-side and returns a normalized result.

Overview

The provider flow is:

mcp_providers.yaml
  -> MCPDiscovery
  -> provider tools/list discovery
  -> normalized tool metadata
  -> Redis discovery/runtime cache
  -> BM25S retrieval and MCP tool routing

Use this page when you want to:

Provider Configuration File

By default, Axiolex reads providers from:

source_files/mcp_providers.yaml

A provider entry looks like this:

providers:
  - id: alphavantage_finance
    name: Alpha Vantage MCP
    transport: streamable-http
    endpoint: https://mcp.alphavantage.co/mcp
    command: null
    args: []
    auth:
      type: api_key
      secret_env: ALPHAVANTAGE_API_KEY
      secret_value: null
    enabled: true
    features:
      supports_streaming: true
    limits:
      max_page_size: 15
      max_requests_per_minute: 60
      max_results: 100
      timeout_seconds: 10

Configuration Fields

Field Required Description
id Yes Stable unique provider identifier. Used in API routes, cache keys, and normalized tool IDs.
name Yes Human-readable provider name shown in the UI.
transport Yes Provider transport. Supported: streamable-http, stdio, a2a.
endpoint For HTTP transports MCP server endpoint URL.
command For stdio-style configs Command name if a provider is represented by a local process.
args No Command arguments for process-based providers.
auth.type No Authentication mode: none, api_key, bearer, or basic.
auth.secret_env For authenticated providers Environment variable that contains the secret.
auth.username For basic auth Non-secret username/account identifier (e.g. Jira email). Stored in YAML as plaintext.
auth.key_param No Query-parameter name for api_key auth. Defaults to api_key.
enabled No Whether the provider participates in discovery.
features.supports_streaming No Indicates whether the provider supports streaming behavior.
limits.max_page_size No Provider-specific page size limit for discovery/adapters.
limits.max_requests_per_minute No Rate limit metadata for provider calls.
limits.max_results No Maximum result count metadata.
limits.timeout_seconds No Timeout metadata for provider operations.

Authentication

For providers that need credentials, store the secret in an environment variable and reference that variable with auth.secret_env.

export ALPHAVANTAGE_API_KEY="your-api-key"

auth:
  type: api_key
  secret_env: ALPHAVANTAGE_API_KEY

For bearer-token providers:

auth:
  type: bearer
  secret_env: CUSTOM_MCP_TOKEN

For basic auth providers (e.g. Jira) that need a username + token pair:

auth:
  type: basic
  username: your-email@domain.com
  secret_env: JIRA_API_TOKEN

The username is a non-secret identifier stored in the YAML. The token is stored encrypted in the secret store (or via the environment variable). For stdio providers, both are passed to the subprocess as environment variables: {SECRET_ENV} (the token) and {SECRET_ENV}_USERNAME (the email).

For unauthenticated providers:

auth:
  type: none
  secret_env: null

AXIOLEX rejects inline credentials in auth.secret_value, provider URL query parameters, and static authorization headers. The backend resolves the value only from auth.secret_env at request time; the UI and provider YAML receive only the environment-variable name. Credential-bearing URLs are redacted in discovery logs.

Add a Provider in YAML

Add a new provider under providers:

providers:
  - id: local_markets
    name: Local Markets MCP
    transport: streamable-http
    endpoint: http://localhost:9001/mcp
    command: null
    args: []
    auth:
      type: none
      secret_env: null
      secret_value: null
    enabled: true
    features:
      supports_streaming: false
    limits:
      max_page_size: 50
      max_requests_per_minute: 60
      max_results: 100
      timeout_seconds: 10

After editing the YAML file, discover tools from the provider through the UI or REST API.

A2A provider example

A2A agents expose skills via an agent card. Axiolex fetches the card at {endpoint}/.well-known/agent-card.json and maps each skill to a catalog tool.

providers:
  - id: veris_finance_a2a
    name: Veris Finance Research (A2A)
    transport: a2a
    endpoint: http://localhost:8100/agents/veris-finance-research-agent/
    command: null
    args: []
    auth:
      type: none
      secret_env: null
    enabled: true
    namespaces:
      - veris.research

A2A execution is synchronous — Axiolex sends a SendMessage request and waits for the result within the configured timeout. The caller sees the same normalized response as an MCP tool.

Manage Providers Through the Web UI

Start the Axiolex service and open the web interface. In the MCP and A2A Providers tab you can:

Manage Providers Through the REST API

List Providers

curl -X GET http://localhost:9700/mcp-providers

Add a Provider

curl -X POST http://localhost:9700/mcp-providers \
  -H "Content-Type: application/json" \
  -d '{
    "id": "local_markets",
    "name": "Local Markets MCP",
    "transport": "streamable-http",
    "endpoint": "http://localhost:9001/mcp",
    "command": null,
    "args": [],
    "auth": {
      "type": "none",
      "secret_env": null,
      "secret_value": null
    },
    "enabled": true,
    "features": {
      "supports_streaming": false
    },
    "limits": {
      "max_page_size": 50,
      "max_requests_per_minute": 60,
      "max_results": 100,
      "timeout_seconds": 10
    }
  }'

Update a Provider

curl -X PUT http://localhost:9700/mcp-providers/local_markets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local Markets MCP",
    "transport": "streamable-http",
    "endpoint": "http://localhost:9001/mcp",
    "command": null,
    "args": [],
    "auth": {
      "type": "none",
      "secret_env": null,
      "secret_value": null
    },
    "enabled": true,
    "features": {
      "supports_streaming": false
    },
    "limits": {
      "max_page_size": 50,
      "max_requests_per_minute": 60,
      "max_results": 100,
      "timeout_seconds": 10
    }
  }'

Disable a Provider

curl -X DELETE http://localhost:9700/mcp-providers/local_markets

This sets enabled to false. If Redis is connected, Axiolex also invalidates cached tools for that provider and reloads the retriever index.

Discover Provider Tools

curl -X GET http://localhost:9700/mcp-providers/local_markets/discover

A successful response includes the normalized tool list and count:

{
  "success": true,
  "provider_id": "local_markets",
  "tools": [],
  "count": 0
}

Discovery and Caching

When discovery succeeds, Axiolex separates tool data into two cache shapes:

This separation lets the MCP server retrieve and rank tools without mixing search text with runtime connection details.

Alpha Vantage Provider

The alphavantage_finance provider has a provider-specific adapter. Use ALPHAVANTAGE_API_KEY for authentication:

export ALPHAVANTAGE_API_KEY="your-alpha-vantage-key"

Example configuration:

- id: alphavantage_finance
  name: Alpha Vantage MCP
  transport: streamable-http
  endpoint: https://mcp.alphavantage.co/mcp
  command: null
  args: []
  auth:
    type: api_key
    secret_env: ALPHAVANTAGE_API_KEY
    secret_value: null
  enabled: true
  features:
    supports_streaming: true
  limits:
    max_page_size: 15
    max_requests_per_minute: 60
    max_results: 100
    timeout_seconds: 10

Troubleshooting