MCP Tools Reference

This document provides a complete reference for all MCP (Model Context Protocol) tools available in the Fulcrum governance server.

Overview

The Fulcrum MCP server provides 19 tools for AI agents to manage governance policies, budgets, approvals, and observability. These tools enable agents to self-govern and integrate with human oversight workflows.

Endpoint: POST /mcp (JSON-RPC 2.0)

Authentication: Bearer token via Authorization header or x-api-key header.

Tool Categories

Category	Tools	Description
Policy Management	7	CRUD operations for governance policies
Budget Management	4	Budget tracking and limits
Approval Workflows	3	Human-in-the-loop approvals
API Key Management	3	API key lifecycle
Observability	2	Metrics and audit logs

---

Policy Management Tools

check_governance

Evaluate policies against an input to determine if an action is allowed.

Input Schema:

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "The action being performed (e.g., 'send_email', 'query_database')"
    },
    "input_text": {
      "type": "string",
      "description": "The input text to evaluate against policies"
    },
    "context": {
      "type": "object",
      "description": "Additional context for policy evaluation"
    }
  },
  "required": ["action", "input_text"]
}

Response: Policy evaluation result with decision (ALLOW/DENY/WARN), matched rules, and actions.

---

list_policies

List all policies for the tenant, optionally filtered by status.

Input Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["ACTIVE", "INACTIVE", "DRAFT", "all"],
      "description": "Filter by policy status (default: all)"
    }
  }
}

Response: Array of policies with id, name, type, status, priority, and rules.

---

get_policy

Get details of a specific policy by ID.

Input Schema:

{
  "type": "object",
  "properties": {
    "policy_id": {
      "type": "string",
      "description": "The unique identifier of the policy"
    }
  },
  "required": ["policy_id"]
}

Response: Full policy details including rules configuration.

---

create_policy

Create a new governance policy.

Input Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Policy name (alphanumeric, dashes, underscores)"
    },
    "description": {
      "type": "string",
      "description": "Human-readable description"
    },
    "policy_type": {
      "type": "string",
      "enum": ["budget", "rate_limit", "content_filter", "approval", "custom"],
      "description": "Type of policy"
    },
    "priority": {
      "type": "integer",
      "description": "Evaluation priority (higher = first)"
    },
    "rules": {
      "type": "object",
      "description": "Policy-specific rule configuration"
    }
  },
  "required": ["name", "policy_type"]
}

Response: Created policy with generated ID.

---

update_policy

Update an existing policy's configuration.

Input Schema:

{
  "type": "object",
  "properties": {
    "policy_id": {
      "type": "string",
      "description": "The policy ID to update"
    },
    "name": {
      "type": "string",
      "description": "New policy name"
    },
    "description": {
      "type": "string"
    },
    "priority": {
      "type": "integer"
    },
    "rules": {
      "type": "object"
    }
  },
  "required": ["policy_id"]
}

Response: Updated policy details.

---

update_policy_status

Enable, disable, or change a policy's status.

Input Schema:

{
  "type": "object",
  "properties": {
    "policy_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": ["ACTIVE", "INACTIVE", "DRAFT"]
    }
  },
  "required": ["policy_id", "status"]
}

Response: Confirmation of status change.

---

delete_policy

Delete a policy permanently.

Input Schema:

{
  "type": "object",
  "properties": {
    "policy_id": {
      "type": "string"
    }
  },
  "required": ["policy_id"]
}

Response: Confirmation of deletion.

---

Budget Management Tools

list_budgets

List all budgets with current spend and status.

Input Schema:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["active", "warning", "exceeded", "all"],
      "description": "Filter by budget status"
    }
  }
}

Response: Array of budgets with limit, current spend, percentage, and status.

---

get_budget

Get details of a specific budget.

Input Schema:

{
  "type": "object",
  "properties": {
    "budget_id": {
      "type": "string"
    }
  },
  "required": ["budget_id"]
}

Response: Full budget details.

---

create_budget

Create a new budget allocation.

Input Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Budget name"
    },
    "scope": {
      "type": "string",
      "enum": ["GLOBAL", "TENANT", "WORKFLOW", "MODEL"],
      "description": "Budget scope level"
    },
    "scope_id": {
      "type": "string",
      "description": "ID of the scoped entity (tenant ID, workflow ID, etc.)"
    },
    "limit_amount": {
      "type": "number",
      "description": "Budget limit in USD"
    },
    "period": {
      "type": "string",
      "enum": ["DAILY", "WEEKLY", "MONTHLY", "QUARTERLY"]
    },
    "action": {
      "type": "string",
      "enum": ["WARN", "SOFT_LIMIT", "HARD_LIMIT"],
      "description": "Action when budget is exceeded"
    },
    "alert_thresholds": {
      "type": "array",
      "items": {"type": "integer"},
      "description": "Percentage thresholds for alerts (e.g., [50, 75, 90])"
    }
  },
  "required": ["name", "limit_amount", "period"]
}

Response: Created budget with generated ID.

---

get_budget_status

Get current status and spend for a budget.

Input Schema:

{
  "type": "object",
  "properties": {
    "budget_id": {
      "type": "string"
    }
  },
  "required": ["budget_id"]
}

Response: Current spend, remaining budget, percentage used, and status.

---

Approval Workflow Tools

list_pending_approvals

List all approvals awaiting human decision.

Input Schema:

{
  "type": "object",
  "properties": {
    "workflow_id": {
      "type": "string",
      "description": "Filter by workflow ID"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of approvals to return (default: 50)"
    }
  }
}

Response: Array of pending approvals with action details and request context.

---

approve_action

Approve a pending action request.

Input Schema:

{
  "type": "object",
  "properties": {
    "approval_id": {
      "type": "string"
    },
    "comment": {
      "type": "string",
      "description": "Optional approval comment"
    }
  },
  "required": ["approval_id"]
}

Response: Confirmation of approval.

---

deny_action

Deny a pending action request.

Input Schema:

{
  "type": "object",
  "properties": {
    "approval_id": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "description": "Reason for denial (required)"
    }
  },
  "required": ["approval_id", "reason"]
}

Response: Confirmation of denial.

---

API Key Management Tools

list_api_keys

List all API keys for the tenant.

Input Schema:

{
  "type": "object",
  "properties": {}
}

Response: Array of API keys with id, name, prefix (first 8 chars), status, and last used timestamp.

---

create_api_key

Create a new API key.

Input Schema:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Key name for identification"
    },
    "description": {
      "type": "string"
    },
    "scopes": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Permission scopes (e.g., ['policies:read', 'policies:write'])"
    }
  },
  "required": ["name"]
}

Response: Created API key with the full key value (shown only once).

---

revoke_api_key

Revoke an existing API key.

Input Schema:

{
  "type": "object",
  "properties": {
    "key_id": {
      "type": "string"
    }
  },
  "required": ["key_id"]
}

Response: Confirmation of revocation.

---

Observability Tools

get_metrics

Get platform metrics for the tenant.

Input Schema:

{
  "type": "object",
  "properties": {
    "metric_type": {
      "type": "string",
      "enum": ["usage", "cost", "policy", "all"],
      "description": "Type of metrics to retrieve"
    },
    "start_time": {
      "type": "string",
      "format": "date-time",
      "description": "Start of time range (ISO 8601)"
    },
    "end_time": {
      "type": "string",
      "format": "date-time",
      "description": "End of time range (ISO 8601)"
    }
  }
}

Response: Metrics including total events, tokens, cost, policy denials, and breakdowns by model/action.

---

get_audit_log

Query the audit log for tenant activity.

Input Schema:

{
  "type": "object",
  "properties": {
    "resource_type": {
      "type": "string",
      "enum": ["Policy", "Budget", "APIKey", "Approval", "User"],
      "description": "Filter by resource type"
    },
    "action": {
      "type": "string",
      "description": "Filter by action (e.g., 'created', 'updated', 'deleted')"
    },
    "actor_id": {
      "type": "string",
      "description": "Filter by actor (user or API key)"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum entries to return (default: 100)"
    }
  }
}

Response: Array of audit log entries with timestamp, actor, action, resource, and changes.

---

MCP Resources

The server also provides read-only resources:

URI	Description
envelopes://latest	Latest execution envelopes
policies://active	Currently active policies
tenant://status	Tenant status and usage
tenant://config	Tenant configuration

---

Error Handling

All tools return errors in JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Policy not found",
    "data": {
      "policy_id": "pol-invalid"
    }
  }
}

Code	Description
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32000	Application error (see message)

---

Example Usage

Claude Desktop Configuration

{
  "mcpServers": {
    "fulcrum": {
      "command": "curl",
      "args": ["-X", "POST", "https://api.fulcrumlayer.io/mcp"],
      "env": {
        "FULCRUM_API_KEY": "your-api-key"
      }
    }
  }
}

JSON-RPC Request

curl -X POST https://api.fulcrumlayer.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_policies",
      "arguments": {
        "status": "ACTIVE"
      }
    }
  }'

---

See Also

• SDK Documentation
• GitOps Policies Guide