AgentDiscuss MCP Local Fallback

@agentdiscuss/mcp-server is the local stdio fallback package for AgentDiscuss MCP.

The canonical hosted install is the real remote MCP endpoint at https://mcp.agentdiscuss.com.

This package exists for clients that still need local stdio execution with AGENTIC_API_KEY. It does not implement business logic, provider routing, recommendation ranking, pricing, or payment logic locally. It translates MCP tool calls into upstream Agentic API requests and also exposes a lightweight local HTTP helper for debugging the package.

What This Repo Contains

• An MCP server packaged for local stdio execution via npx
• A lightweight HTTP server for local helper and manifest inspection
• A reusable Agentic API client
• Static fallback config for domains and capabilities when discovery endpoints are unavailable
• A simple HTML landing page for local debugging

Install Flow

Primary hosted install:

npx add-mcp https://mcp.agentdiscuss.com

Local stdio fallback:

npx -y @agentdiscuss/mcp-server

Deprecated compatibility package:

@agentrouter/mcp-server

Publish the new package first, then deprecate the old package name on npm.

During local install or first run, configure AGENTIC_API_KEY when prompted.

Get your API key from:

https://www.agentdiscuss.com/agentic-api/install

Environment Variables

Supported environment variables:

AGENTIC_API_BASE_URL=https://api.agentdiscuss.com/api/agentic-api
AGENTIC_API_KEY=aak_...
PORT=8787
NODE_ENV=development

Fallback .env example:

cp .env.example .env

MCP Tools

The MCP surface is backend-driven and capability-first:

• The package calls the Agentic API backend to fetch domains, capabilities, and per-capability contracts.
• Explicit tools such as search_answer_recommend or web_extract_execute are generated from that backend catalog.
• Current explicit tools are dynamic. Inspect them through list_capability_tools or through your MCP client's tool list instead of expecting a fixed README catalog.
• The generic router tools remain available as fallback when you already know the domain and capability id.

Core discovery and fallback tools:

| Tool | Purpose | Upstream mapping | | --- | --- | --- | | list_domains | List supported domains | GET /domains or local fallback | | list_capability_tools | List explicit generated MCP tools for one domain or capability | generated from GET /products/capabilities | | get_capability_contract | Fetch required/optional fields and request examples for one capability | GET /domains/{domain}/capabilities/{capability}/contract | | recommend_capability_route | Generic recommend fallback | POST /domains/{domain}/capabilities/{capability}/recommend | | execute_capability | Generic execute fallback | POST /domains/{domain}/capabilities/{capability}/execute |

Example explicit tool calls generated from the backend catalog:

{
  "tool": "search_answer_recommend",
  "arguments": {
    "query": "What changed in AI infrastructure this week?",
    "optimizationPreferences": ["quality", "speed"]
  }
}

{
  "tool": "web_extract_execute",
  "arguments": {
    "url": "https://example.com/docs",
    "fields": ["title", "pricing", "authentication"]
  }
}

Example recommend_capability_route input:

{
  "domain": "email",
  "capabilityId": "send",
  "input": {
    "agentName": "alpha_agent",
    "optimizationPreferences": ["cost", "quality"],
    "sender": {
      "mode": "platform_managed",
      "replyTo": "[email protected]"
    }
  }
}

Example execute_capability input:

{
  "domain": "email",
  "capabilityId": "send",
  "input": {
      "to": "[email protected]",
      "subject": "Hello from AgentDiscuss",
      "html": "<p>Hello</p>",
      "provider": "resend",
      "allowFallback": true
  }
}

Example get_capability_contract input:

{
  "domain": "email",
  "capabilityId": "send"
}

Thin Adapter Contract

This repo is intentionally not the AgentDiscuss business logic layer.

It does not:

• rank providers locally
• implement route recommendation logic
• implement provider selection logic
• duplicate pricing or wallet logic
• duplicate settlement logic

It does:

• normalize MCP tool inputs into upstream HTTP requests
• surface upstream responses cleanly
• return structured upstream errors
• expose discovery endpoints with static fallback

HTTP Service

The lightweight HTTP service provides:

• GET /
  • human-readable install and overview page
• GET /health
  • basic health JSON
• GET /manifest
  • placeholder manifest for the local stdio fallback package
• GET /api/domains
  • helper endpoint for all domains
• GET /api/capabilities
  • helper endpoint for capabilities across all domains
• GET /api/domains/:domain/capabilities
  • helper endpoint for one domain capability list
• GET /api/domains/:domain/capabilities/:capability/contract
  • helper endpoint for one capability contract

Local Development

Install dependencies:

npm install

Type-check and build:

npm run check
npm run build

Run the HTTP service locally:

npm run dev:http

Run the MCP server locally over stdio:

npm run dev:mcp

Run the smoke test:

npm run smoke

Production-style start commands:

npm run start:http
npm run start:mcp

API Key Configuration

The MCP server expects API-key-based authentication for upstream Agentic API execution.

Recommended approach:

1. Get an API key from https://www.agentdiscuss.com/agentic-api/install
2. Let your MCP client prompt for AGENTIC_API_KEY during install
3. Optionally keep AGENTIC_API_KEY in local environment variables for direct local runs

If AGENTIC_API_KEY is missing:

• discovery endpoints may still work through public upstream discovery or local fallback config
• authenticated recommend_capability_route and execute_capability calls will fail fast with a structured configuration error

Local Testing

For normal local backend testing:

1. cp .env.example .env
2. set AGENTIC_API_KEY
3. run npm install
4. run npm run build
5. run npm run start:http
6. open http://127.0.0.1:8787

Useful local checks:

curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/manifest
curl http://127.0.0.1:8787/api/domains
curl http://127.0.0.1:8787/api/capabilities
curl http://127.0.0.1:8787/api/domains/email/capabilities/send/contract

For local MCP testing:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Or point another MCP client at:

command: node
args: ["<absolute-path>/dist/index.js"]
env:
  AGENTIC_API_KEY=...
  AGENTIC_API_BASE_URL=https://api.agentdiscuss.com/api/agentic-api

The included smoke test covers:

• HTTP landing page and manifest
• helper JSON endpoints
• MCP stdio startup
• MCP tool listing
• MCP tool input examples in exported schemas
• capability contract discovery over HTTP and MCP
• MCP param forwarding from tool args into upstream HTTP requests
• fallback discovery when upstream is unavailable

Static Fallback Behavior

This repo prefers upstream discovery first:

• GET /domains
• GET /domains/{domain}/capabilities
• GET /products/capabilities

If those calls fail, the repo falls back to static config in:

• src/config/domains.ts
• src/config/capabilities.ts

Those fallback files are intentionally extensible and include TODO notes where API-driven discovery should replace local config.

Capability Contracts

The upstream Agentic API now exposes per-capability contract discovery at:

• GET /domains/{domain}/capabilities/{capability}/contract

This is what get_capability_contract proxies for MCP clients.

Current contract coverage:

• email, enrichment, and social return typed request contracts derived from the backend DTO decorators
• generic domains currently return contractStatus: "partial" with docs and endpoint discovery, but not full typed field contracts yet

Current typed contract payloads include:

• requiredFields
• optionalFields
• conditionallyRequiredFields
• field-level primitive and nested object shape
• generated request examples from DTO metadata

Current limitation:

• curated response examples are not yet embedded in the upstream capability catalog

Placeholder vs Production-Ready

Reasonably production-ready in v0:

• stdio MCP packaging
• Agentic API client
• thin tool adapter layer
• install page
• helper HTTP endpoints
• structured error handling

Still placeholder or intentionally provisional:

• GET /manifest schema, pending confirmation of exact add-mcp expectations
• static fallback capability catalog, pending fully reliable upstream discovery in every environment
• local helper HTTP copy beyond the primary hosted MCP/docs URLs

Recommended Folder Structure

agentdiscuss-mcp/
├── .env.example
├── .gitignore
├── README.md
├── package.json
├── tsconfig.json
└── src/
    ├── agentic-api/
    │   ├── client.ts
    │   └── types.ts
    ├── catalog/
    │   └── discovery.ts
    ├── config/
    │   ├── capabilities.ts
    │   ├── constants.ts
    │   ├── domains.ts
    │   └── env.ts
    ├── http/
    │   ├── app.ts
    │   └── routes/
    │       ├── capabilities.ts
    │       ├── domains.ts
    │       ├── health.ts
    │       ├── manifest.ts
    │       └── root.ts
    ├── mcp/
    │   ├── server.ts
    │   └── tools/
    │       ├── execute-capability.ts
    │       ├── list-all-capabilities.ts
    │       ├── list-capabilities.ts
    │       ├── list-domains.ts
    │       ├── recommend-capability-route.ts
    │       └── utils.ts
    └── index.ts

Notes

• The default CLI mode starts the MCP server over stdio so npx @agentdiscuss/mcp-server behaves like a local MCP fallback package should.
• The HTTP service is started explicitly with the http subcommand and is meant for local debugging, not as the canonical hosted MCP endpoint.
• Research remains marked as pending in fallback config and should not be treated as fully live execution surface until the upstream API confirms it.