# MCP Trust Oracle — Agent Developer Guide

The ARF Trust Oracle lets AI agents check whether an organization's infrastructure is safe for agent interaction *before* calling their APIs. This prevents agents from hitting undocumented rate limits, failing authentication with human-only OAuth flows, or making irreversible state changes without rollback support.

## Why Agents Should Check Readiness

Most APIs were built for human-driven applications. When an autonomous agent calls an API, it faces risks that humans don't:

- **Silent throttling**: No `X-RateLimit-*` headers means the agent can't self-throttle and will get 429s without warning
- **Human-only auth**: OAuth2 authorization code flows require a browser — agents need `client_credentials` grants
- **No rollback**: If an agent makes a mistake, it needs idempotency keys or compensation endpoints to undo actions
- **No kill switch**: Without revocation APIs, a compromised agent credential can't be quickly disabled

The Trust Oracle scores organizations across these dimensions and returns a simple `safe_for_agents` boolean plus detailed warnings.

---

## API Reference

### Check Trust (Full Assessment)

```
GET https://getjackfruit.ai/api/v1/trust/{domain}
```

**Response:**
```json
{
  "domain": "stripe.com",
  "trust_score": 34.8,
  "tier": "Developing",
  "safe_for_agents": false,
  "warnings": [
    "No rate limit headers detected -- agent may be throttled without warning",
    "No non-human identity support -- agent cannot authenticate with scoped credentials"
  ],
  "strengths": [
    "Public API available",
    "AI-discoverable documentation and presence"
  ],
  "recommendations": {
    "rate_limiting": "Implement X-RateLimit-* headers for agent self-throttling",
    "identity": "Add OAuth2 client_credentials flow for machine-to-machine auth"
  },
  "last_assessed": "2026-04-02T12:00:00Z",
  "assessment_url": "https://getjackfruit.ai/assessment/17789"
}
```

**`safe_for_agents` logic:**
- D1 (API & Interface Layer) >= L1 (score >= 20) **AND**
- D2 (Identity, Auth & Permissions) >= L1 **AND**
- D4 (State Management & Operational Safety) >= L1

All three must be met. If any is missing, `safe_for_agents` is `false` with specific warnings.

### Check Dimension Readiness

```
GET https://getjackfruit.ai/api/v1/trust/{domain}/dimension/{dimension}
```

The `dimension` parameter accepts either a name (`api`, `identity`, `safety`, `interop`, `observability`, `data`, `devops`, `governance`) or a number (`1`-`19`).

**Response:**
```json
{
  "domain": "stripe.com",
  "dimension": {
    "number": 2,
    "name": "Identity, Auth & Permissions",
    "question": "Can agents authenticate and operate within safe boundaries?"
  },
  "score": 12.5,
  "label": "Nascent",
  "checks": [
    {
      "check_id": "2.1",
      "name": "Non-human identity support",
      "maturity_level": 0,
      "maturity_label": "L0 (None)",
      "remediation": "Implement service accounts or API keys with scoped permissions"
    }
  ],
  "total_checks": 10,
  "assessed_checks": 8
}
```

---

## MCP Tool Integration

If your agent runtime supports MCP (Model Context Protocol), connect to the ARF MCP server and use these tools directly:

### Tool: `check_trust`

```
name: check_trust
description: "Check if an organization's infrastructure is safe for agent interaction before calling their APIs"
parameters: { domain: string }
```

Returns the same payload as the REST API trust endpoint.

### Tool: `check_api_readiness`

```
name: check_api_readiness
description: "Check if a specific API dimension is ready for agent consumption"
parameters: { domain: string, dimension: "api"|"identity"|"safety"|"interop"|... }
```

Returns dimension-specific readiness with per-check maturity levels.

### MCP Server Configuration

Add to your Claude Desktop config (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "arf": {
      "command": "python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/path/to/jackfruit/backend"
    }
  }
}
```

---

## Framework Integration Examples

### LangChain

```python
from langchain.tools import tool
import requests

@tool
def check_api_trust(domain: str) -> dict:
    """Check if an organization's API is safe for agent interaction.

    Call this before making API requests to external services.
    Returns trust score, safety boolean, and specific warnings.
    """
    resp = requests.get(
        f"https://getjackfruit.ai/api/v1/trust/{domain}",
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()


@tool
def check_dimension_readiness(domain: str, dimension: str) -> dict:
    """Check a specific readiness dimension (api, identity, safety, interop) for a domain."""
    resp = requests.get(
        f"https://getjackfruit.ai/api/v1/trust/{domain}/dimension/{dimension}",
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()


# Usage in an agent chain:
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")
tools = [check_api_trust, check_dimension_readiness]

# The agent will automatically call check_api_trust before interacting
# with unknown APIs, using the warnings to adjust its behavior.
```

### CrewAI

```python
from crewai import Agent, Task, Crew
from crewai_tools import tool
import requests


@tool("Check API Trust")
def check_api_trust(domain: str) -> str:
    """Check if an organization's API is safe for agent interaction before calling it.
    Returns trust score, safety status, and warnings about readiness gaps."""
    resp = requests.get(f"https://getjackfruit.ai/api/v1/trust/{domain}", timeout=10)
    data = resp.json()

    status = "SAFE" if data["safe_for_agents"] else "UNSAFE"
    warnings = "\n".join(f"  - {w}" for w in data.get("warnings", []))

    return f"""
Trust Assessment for {domain}:
  Score: {data['trust_score']}/100 ({data['tier']})
  Agent Safety: {status}
  Warnings:
{warnings}
"""


researcher = Agent(
    role="API Integration Researcher",
    goal="Evaluate external APIs before integration",
    tools=[check_api_trust],
    verbose=True,
)

task = Task(
    description="Check if stripe.com is safe for our payment agent to use",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
```

### AutoGen

```python
import requests
from autogen import ConversableAgent


def check_trust(domain: str) -> dict:
    """Check if a domain's API infrastructure is safe for agent interaction."""
    resp = requests.get(f"https://getjackfruit.ai/api/v1/trust/{domain}", timeout=10)
    return resp.json()


# Register as a tool for AutoGen agents
assistant = ConversableAgent(
    name="api_safety_checker",
    system_message=(
        "Before calling any external API, always check its trust score "
        "using the check_trust function. If safe_for_agents is false, "
        "warn the user and explain the specific risks."
    ),
    llm_config={"tools": [{"type": "function", "function": {
        "name": "check_trust",
        "description": "Check if a domain is safe for agent API interaction",
        "parameters": {
            "type": "object",
            "properties": {"domain": {"type": "string"}},
            "required": ["domain"],
        },
    }}]},
)

assistant.register_function(
    function_map={"check_trust": check_trust}
)
```

### Generic Python (requests)

```python
import requests

def is_safe_for_agent(domain: str) -> bool:
    """Quick check: is this domain safe for agent interaction?"""
    try:
        resp = requests.get(
            f"https://getjackfruit.ai/api/v1/trust/{domain}",
            timeout=5,
        )
        data = resp.json()
        return data.get("safe_for_agents", False)
    except Exception:
        # If the trust oracle is unreachable, default to cautious
        return False


# Guard pattern for agent workflows
def call_external_api(domain: str, endpoint: str, **kwargs):
    """Call an external API with trust pre-check."""
    if not is_safe_for_agent(domain):
        raise RuntimeError(
            f"Agent safety check failed for {domain}. "
            f"Review trust assessment at https://getjackfruit.ai/trust"
        )
    return requests.request(**kwargs, url=f"https://{domain}{endpoint}")
```

---

## Trust Badge

Organizations can embed their ARF trust score as a badge:

```markdown
![ARF Trust Score](https://getjackfruit.ai/api/v1/badge/{domain}.svg)
```

Example:
```markdown
![ARF Trust Score](https://getjackfruit.ai/api/v1/badge/stripe.com.svg)
```

This renders a shields.io-style badge with the score and color-coded tier.

---

## Scoring Overview

The trust score is derived from the Agent Readiness Framework (ARF), which evaluates organizations across 19 dimensions grouped into 6 pillars:

| Pillar | Dimensions | What It Measures |
|--------|-----------|-----------------|
| Foundation | D1 (API), D2 (Identity), D3 (Observability), D12 (Runtime) | Core infrastructure agents depend on |
| Intelligence | D5 (Data), D13 (Knowledge) | Data and knowledge for agent reasoning |
| Operations | D4 (Safety), D6 (DevOps), D14 (Architecture) | Operational reliability and safety |
| Security | D17 (Supply Chain), D18 (Access), D19 (Threats) | AI-specific security controls |
| Governance | D11 (GRC), D15 (Cost), D16 (Human-Agent) | Oversight and compliance |
| External | D7 (Discovery), D8 (Ecosystem), D9 (Interop), D10 (Presence) | External discoverability and interop |

**Maturity Levels:**
- **L0 (None)** — No capability detected
- **L1 (Basic)** — Minimal implementation
- **L2 (Established)** — Standard implementation
- **L3 (Advanced)** — Best-in-class implementation

**Tier Labels:**
- Nascent (0-20) | Developing (20-45) | Progressing (45-70) | Advanced (70-90) | Leading (90+)