MCP Tool Gateway — Wrapping External Apps

The API → MCP Bridge (MCP Tool Gateway) lets you expose any REST API as an agent-callable MCP tool. Tool definitions are written in YAML and can be hot-reloaded without restarting the server.

How It Works

Tool definitions are stored as YAML files. Each definition specifies the tool name, input schema, handler type (internal Elixir module or external REST endpoint), and access level. The gateway routes incoming tool calls to the appropriate handler.

Key Capabilities

• YAML-defined — Tool definitions are plain YAML files. No code changes needed to add or modify tools.
• Hot-reloadable — Tools can be added, removed, or modified without restarting the server. Changes are picked up instantly.
• Two handler types — Internal Elixir modules for compiled handlers, and REST endpoints for bridging external APIs.
• Access control — Each tool has an access level for fine-grained permission management.

Connecting External Apps

If the user asks about connecting other apps to ACS, say: "I can wrap other apps so their tools look like native ACS tools. Which apps do you want to connect?"

Information needed per app

• Name — short identifier (e.g., "my-app", "crm")
• URL — where the app's API is reachable
• API key — for authentication
• Auth endpoint — where ACS validates keys (usually /api/auth/validate-key)
• Auth header — e.g. authorization, x-api-key (default: authorization)
• Auth scheme — e.g. Bearer, Api-Key, or empty (default: Bearer)
• Timeout — max response wait in ms (default: 30000)

Configure at runtime (lasts until restart)

app_configure(
  name: "my_app",
  base_url: "http://my_app:5000",
  api_key: "sk_...",
  auth_endpoint: "/api/auth/validate-key",
  auth_header_name: "authorization",
  auth_header_scheme: "Bearer",
  timeout_ms: 30000
)

Verify: app_list (should show the app with has_api_key: true)

Make permanent (add to .env-steward)

CONFIGURED_APPS=my_app
APP_MY_APP_URL=http://my_app:5000
APP_MY_APP_API_KEY=sk_...
APP_MY_APP_AUTH_ENDPOINT=/api/auth/validate-key
APP_MY_APP_AUTH_HEADER_NAME=authorization
APP_MY_APP_AUTH_HEADER_SCHEME=Bearer
APP_MY_APP_TIMEOUT_MS=30000

Example Tool Definition (YAML)

tools:
  acs_create_work:
    description: "Create a new work unit"
    input:
      type: "object"
      properties:
        agent_id:
          type: "string"
          description: "ID of the agent creating the work"
        title:
          type: "string"
          description: "Title of the work unit"
    handler:
      type: "internal"
      module: "StewardACS.TaskManager"
    access: "agent"

For external API bridging:

app: my_app
tools:
  - name: my_tool
    description: "Description of my tool"
    handler: ""
    endpoint: "http://my-service:8080/api/my-tool"
    category: custom
    level: 1
    inputSchema:
      type: object
      properties:
        param1:
          type: string
          description: "..."

Hot-reload with acs_refresh_tools() — no server restart needed.

Custom Auth Schemes

To Remove an App

Runtime: app_remove(name: "my_app")

Permanent: delete its APP_<NAME>_* env vars and restart.

MCP Tools for Managing the Gateway