Skip to content

MCP Server

The MCP (Model Context Protocol) servers expose CRED platform capabilities as tools for AI assistants. Their tools are consumed by cred-agent-ai's single-agent assistant (and by the vertical agents); the assistant loads them alongside the cred-platform CLI, its primary data edge.

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

Repository

Architecture

flowchart TB
    credAgent["cred-agent-ai\nsingle agent (loads the visible tool set)"]
    gateway["IBM MCP Context Forge Gateway\nAggregates tools, adds prefixes"]
    graphql["graphql-mcp-server\nGraphQL operations as tools"]
    assistant["assistant-mcp-server\nplatform help, metrics, scoring, reports…"]
    datascience["data-science-mcp-server\npipeline management"]
    devpipe["dev-pipeline-mcp-server\ninternal dev-cycle tools"]

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

MCP Servers

Server Language Stack Tools
graphql-mcp-server Config Apollo MCP binary, Docker GraphQL operations (search, lists, campaigns, workflows, etc.) exposed as individual tools
assistant-mcp-server Python FastAPI, FastMCP AI tools: platform_assistant (RAG platform help), nl_company_search, metrics, scoring, reports, matching, and auto-registered tool modules
data-science-mcp-server Python FastAPI, FastMCP Pipeline tools (run, list, status, scaffold, deploy). Internally an encapsulated supervisor + subagent LangGraph, exposed as single tools — see Agent architecture
dev-pipeline-mcp-server Python FastAPI, FastMCP Internal, not customer-facing — dev-cycle tools (PR review/routing/merge, planning) consumed by the agentic dev workflow
mcp-gateway Python IBM MCP Context Forge Aggregates all servers behind one endpoint

platform_assistant is a tool, not the assistant. It is a read-only, RAG-over-docs helper exposed by assistant-mcp-server. It is not the customer-facing cred-agent-ai assistant — the single agent calls it as one of its tools.

MCP Gateway

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

  • Aggregates tools from all 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 scoping)

Tools may carry an @agents: tag in their description. Historically this drove supervisor/subagent routing; today its status depends on the consumer:

  • The main single-agent assistant does not currently read @agents tags. It loads the whole visible tool set (minus the CLI-superseded and excluded tools) and lets the one agent choose. The tag is parsed out and stripped before the LLM sees the description, but it does not gate which tools the assistant gets. Re-enabling per-agent tag scoping for the main assistant is a small change if ever desired — the parseAgentTags utility still exists and would just need to be wired into selectVisibleTools (the same parse the code below still uses).
  • The vertical agents still honor the tag. The vertical-agent runner (e.g. outbound prospecting) uses parseAgentTags to scope which tools an agent may call, so the tag is not dead — keep it on tools a vertical agent relies on.

So the tag is optional and harmless for general tools, and meaningful where a vertical agent depends on it.

Format

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

# Search companies in the CRED database.
# ... description ...
# @agents: <scope>
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: <scope>
    """

The valid scope names are defined by the consuming vertical agents, not by the (removed) supervisor's old domain list. Check the vertical-agent runner / .cursor/rules/agent-tags.mdc in cred-mcp for the current vocabulary before relying on a specific name.

How It Works

  1. Tool definitions — GraphQL operations are .graphql files in data/operations/; Python tools use @mcp.tool() decorators.
  2. Gateway aggregation — the IBM gateway merges all tools and adds prefixes.
  3. cred-agent-ai — the single agent discovers the aggregated catalog, selects its visible tool set (selectVisibleTools: drops CLI-superseded + excluded tools, applies source/vendor gates), and runs one agent loop over the result. No supervisor, no per-subagent partitioning.
  4. Vertical agents (separate path) — use parseAgentTags to scope tools per agent where applicable.

Adding a New Tool

GraphQL operation:

  • Create a .graphql file in graphql-mcp-server/data/operations/ (PascalCase)
  • Add # comment block with description
  • (Optional) Add # @agents: <scope> if a vertical agent needs to scope it
  • 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
  • (Optional) Add @agents: <scope> in the docstring if a vertical agent needs it
  • Register in main.py

Note

The main single-agent assistant picks up the new tool automatically once it's in the aggregated catalog and not CLI-superseded/excluded — no @agents tag needed for it. Add the tag only where a vertical agent relies on tag scoping.