Skip to content

MCP Server

The MCP (Model Context Protocol) servers expose CRED platform capabilities as tools for AI assistants. Tools are consumed by cred-agent-ai's supervisor/subagent architecture.

  • Setup — Running the servers locally
  • Usage — Testing with Claude Desktop

Repository

Architecture

flowchart TB
    credAgent["cred-agent-ai\nSupervisor → partitionTools → Agents"]
    gateway["IBM MCP Context Forge Gateway\nAggregates tools, adds prefixes"]
    graphql["graphql-mcp-server\n~109 tools"]
    assistant["assistant-mcp-server\n~30 tools"]
    datascience["data-science-mcp-server\n~6 tools"]

    credAgent --> gateway
    gateway --> graphql
    gateway --> assistant
    gateway --> datascience

MCP Servers

Server Language Stack Tools
graphql-mcp-server Config Apollo MCP binary, Docker ~109 GraphQL operations (search, lists, campaigns, workflows, etc.)
assistant-mcp-server Python FastAPI, FastMCP ~30 AI tools (platform help, metrics, scoring, reports, matching, etc.)
data-science-mcp-server Python FastAPI, FastMCP 6 pipeline tools (run, list, status, scaffold, deploy)
mcp-gateway Python IBM MCP Context Forge Aggregates all servers behind one endpoint

MCP Gateway

The IBM MCP Context Forge gateway sits between cred-agent-ai and the backend servers. It:

  • Aggregates tools from all 3 servers into a single tools/list response
  • Adds server-name prefixes to tool names (e.g., graphql-mcp-SearchCompanies)
  • Handles OAuth and JWT forwarding
  • Deployed on GCP Cloud Run

@agents Tags (Tool Routing)

Every MCP tool must include an @agents: tag in its description to control which cred-agent-ai subagent receives it.

Format

GraphQL operations — last # comment line before query/mutation: 

# Search companies in the CRED database.
# ... description ...
# @agents: intelligence_agent, lists_agent
query SearchCompanies(...) {

Python tools — in the docstring summary section (before Args/Returns): 

def platform_assistant(question: str) -> dict:
    """
    Answer questions about the CRED platform.
    @agents: supervisor
    """

Valid Agent Names

Agent Domain
supervisor Supervisor direct tools (currentUser, platform_assistant)
intelligence_agent Entity search, profiles, financial data
lists_agent Lists, campaigns, message sequences
analytics_agent Dashboards, metrics, scoring, charts
workflows_agent Automations, triggers, alerts
data_ops_agent Imports, sources, CRM sync, matching
report_agent Report builder
data_science_agent Pipeline management

Rules

  • Comma-separated for multiple agents: @agents: intelligence_agent, lists_agent
  • cred-agent-ai parses and strips the tag before the LLM sees the description
  • Tools without a tag fall back to a safety-net fallback agent (legacy behavior)
  • See .cursor/rules/agent-tags.mdc in cred-mcp for the full specification

How It Works

  1. Tool definitions — GraphQL operations are .graphql files in data/operations/; Python tools use @mcp.tool() decorators
  2. @agents tag — Each tool declares its target agent(s) in its description
  3. Gateway aggregation — IBM gateway merges all tools and adds prefixes
  4. cred-agent-ai — partitionTools() parses tags, routes tools to the correct subagent
  5. Supervisor routing — The supervisor LLM delegates to the right agent based on user intent

Adding a New Tool

GraphQL operation:

  • Create a .graphql file in graphql-mcp-server/data/operations/ (PascalCase)
  • Add # comment block with description
  • Add # @agents: <agent_name> as the last comment line
  • If RELOAD_ON_DATA_CHANGE=true, the server auto-restarts

Python tool (assistant or data-science):

  • Create tool function with @mcp.tool() decorator
  • Add docstring with description
  • Add @agents: <agent_name> in the docstring summary section (before Args/Returns)
  • Register in main.py

Note

No changes needed in cred-agent-ai — the @agents tag handles routing automatically.