# loan_intelligence - AI Agent Integration

This file describes how an AI agent can interact with loan_intelligence via the Model Context Protocol (MCP).

## Connection

- **MCP endpoint:** `https://loanintelligence.ai/api/plugins/mcp/mcp`
- **Protocol:** Streamable HTTP (JSON-RPC 2.0)
- **Content-Type:** `application/json`

## Authentication

MCP access is tied to the user's account.

1. The user signs in with a browser at `https://loanintelligence.ai`.
2. The user creates an API key at `https://loanintelligence.ai/dashboard/keys`.
3. The key is shown once. Store it in the agent's local secret store or environment, not in prompts, project files, shell history, chat transcripts, or logs.
4. Send the key on every MCP request:

```
Authorization: Bearer <your-api-key>
```

Use the same key for direct API calls and MCP calls when both surfaces are available. Rotate or revoke keys from the account/API-key dashboard if a key may have been exposed.

## Capabilities

Discover current capabilities with `tools/list`. Tool names are stable enough to automate against, but agents should still call `tools/list` at session start so they can adapt when the project adds, removes, or renames tools.

## Other Tools

### loan_intelligence_quote_package

Create an auditable Loan Intelligence package quote from the canonical deduction catalog.

**Parameters:**
- `idempotencyKey`: 
- `isComplexBundle`: 
- `isDeletionOnlyReaggregate`: 
- `isUnchangedReprocess`: 
- `packageId`: 
- `sourceDocumentCount`: 
- `sourceDocuments`: 
- `sourcePageCount`: 
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_process_package

Submit an ephemeral package for processing through the canonical quote, reservation, queue, and worker path.

**Parameters:**
- `idempotencyKey`: 
- `isComplexBundle`: 
- `packageFingerprint`: 
- `sourceDocuments` (required): 
- `title`: 
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_get_package_status

Read durable package processing status without exposing queue or cache internals.

**Parameters:**
- `packageId` (required): 
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_get_package_results

Read durable package result manifests, source references, and output links.

**Parameters:**
- `packageId` (required): 
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_list_packages

List durable packages for the authenticated user in a workspace.

**Parameters:**
- `limit`: 
- `offset`: 
- `status`: 
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_get_credit_policy

Read the authenticated user's workspace credit policy for package processing.

**Parameters:**
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_update_credit_policy

Update package credit controls for the authenticated user in a workspace.

**Parameters:**
- `autoProcessEnabled`: Allow future batch/Drive/API work to continue automatically while policy and credits allow it.
- `maxPackageCreditsCents`: Maximum centi-credits allowed for a single package reservation. Null means no cap.
- `quoteConfirmationRequired`: Require explicit quote confirmation before workspace/client processing starts.
- `workspaceId` (required): Durable Loan Intelligence workspace ID.

### loan_intelligence_get_credit_balance

Read the authenticated user's Stack billing credit balance.

**Parameters:**
None

## Quick Start

1. Ask the user to sign in and create an API key at `https://loanintelligence.ai/dashboard/keys`.
2. Store the key in a local secret store or environment variable controlled by the agent runtime.
3. Initialize the MCP session, call `tools/list`, then call the specific tool needed for the user's task.

### Initialize

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "agent", "version": "1.0.0" }
  }
}
```

### List Tools

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

### Call A Tool

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "loan_intelligence_quote_package",
    "arguments": {}
  }
}
```

## Safety Rules

- Never put the API key in a URL query string.
- Never print the API key in logs or user-visible responses.
- Treat account, billing, checkout, deletion, and publishing tools as user-confirmed actions.
- For browser-only actions such as checkout or cancellation confirmation, return the URL to the user instead of trying to automate payment or account confirmation inside the agent.