> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting your AI agent

> How to connect your AI agent to Grand Central's MCP server

Once you've enabled tools and generated your subscription key in the admin portal, you have everything needed to connect agents. The following sections walk through configuration for popular AI platforms (Claude Desktop, Microsoft Copilot Studio) and custom integrations using the MCP SDK. The setup is straightforward: add your endpoint URL and subscription key to your agent's configuration, and the agent can immediately start discovering and invoking banking tools.

## Prerequisites

Before connecting, ensure you have:

<CardGroup cols={2}>
  <Card title="MCP endpoint URL" icon="link">
    Your unique Grand Central MCP server URL
  </Card>

  <Card title="Subscription key" icon="key">
    API subscription key for authentication
  </Card>

  <Card title="JWT configuration" icon="id-card">
    User authentication token details
  </Card>

  <Card title="AI agent" icon="robot">
    Claude Desktop, Microsoft Copilot, or custom MCP client
  </Card>
</CardGroup>

## Configuration

Each AI platform has slightly different configuration patterns, but the core information is the same: **endpoint URL, subscription key, and optional JWT token for user context**. Choose the section below that matches your agent platform.

### Claude desktop

Claude Desktop uses a JSON configuration file (typically `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS). Add Grand Central as an MCP server:

```json theme={"system"}
{
  "mcpServers": {
    "grandcentral": {
      "command": "mcp",
      "args": ["remote", "https://gc-prod-instance.example.com/mcp"],
      "env": {
        "SUBSCRIPTION_KEY": "a1b2c3d4e5f6g7h8i9j0"
      }
    }
  }
}
```

If you need user-scoped operations (e.g., fetching a specific customer's transaction history), add the JWT token to the `env` object:

```json theme={"system"}
"env": {
  "SUBSCRIPTION_KEY": "a1b2c3d4e5f6g7h8i9j0",
  "JWT_TOKEN": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**Restart Claude Desktop** after editing the config file. Claude will automatically discover tools on next launch.

### Microsoft Copilot Studio

Copilot Studio supports MCP servers through its **plugin system**. Add Grand Central as a plugin:

1. Open Copilot Studio and navigate to **Plugins** → **Add Plugin**
2. Select **Model Context Protocol** as the plugin type
3. Fill in the configuration form:
   * **Name**: `Grand Central Banking Tools`
   * **URL**: `https://gc-prod-instance.example.com/mcp`
   * **Auth Type**: `Bearer Token + Subscription Key`
   * **Subscription Key**: Your subscription key (e.g., `a1b2c3d4e5f6g7h8i9j0`)
   * **Bearer Token** (optional): JWT token for user-scoped operations

The plugin will appear in your Copilot's available tools list after saving. Copilot automatically discovers tools from the MCP server and makes them available during conversations.

### Custom MCP client

If you're building a custom agent or integrating Grand Central into an existing application, use the **MCP SDK** to connect programmatically. Here's a TypeScript example:

```typescript theme={"system"}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const client = new Client({
  name: "jetbank-lending-agent",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}  // Declare that this client supports tool invocation
  }
});

await client.connect({
  command: "mcp",
  args: ["remote", "https://gc-prod-instance.example.com/mcp"],
  env: {
    "SUBSCRIPTION_KEY": process.env.GC_SUBSCRIPTION_KEY,
    "JWT_TOKEN": process.env.GC_JWT_TOKEN  // Optional, for user-scoped ops
  }
});

// Client is now connected and can list/invoke tools
const tools = await client.request({ method: "tools/list" });
console.log(`Discovered ${tools.tools.length} banking tools`);
```

The SDK handles **JSON-RPC protocol details, connection management, and error handling** automatically. You just need to provide credentials and endpoint configuration.

## Authentication

Grand Central requires **subscription key authentication** for all requests, with optional **JWT token authentication** for user-scoped operations. The authentication model mirrors Azure API Management patterns - familiar if you've worked with Azure services.

**Subscription keys** identify your agent or application and enforce rate limits tied to your subscription tier. Include the key in all requests using the `Ocp-Apim-Subscription-Key` header:

```http theme={"system"}
POST /mcp HTTP/1.1
Host: gc-prod-instance.example.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0

{"jsonrpc": "2.0", "method": "tools/list", "id": 1}
```

**JWT tokens** provide user context for operations that need to know *which customer* the agent is acting on behalf of. For example, `getTransactionHistory` might require a JWT containing the customer ID claim. Add JWT tokens via the `Authorization` header:

```http theme={"system"}
POST /mcp HTTP/1.1
Host: gc-prod-instance.example.com
Content-Type: application/json
Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{"jsonrpc": "2.0", "method": "tools/call", "params": {...}, "id": 2}
```

Most tools work with **subscription key only** - you don't need user context for operations like currency conversion or fetching exchange rates. Check tool schemas during discovery to see which operations require JWT tokens (look for `x-mcp-requires-user-context: true` in OpenAPI definitions).

<Warning>
  **Never commit credentials to version control.** Store subscription keys and JWT tokens in environment variables (`.env` files excluded via `.gitignore`) or secure vaults (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault). Rotate keys regularly and revoke compromised keys immediately via the Grand Central admin portal.
</Warning>

## Testing your connection

Before integrating Grand Central into production workflows, verify that your credentials work and tools are accessible. Use `curl` or any HTTP client to test the connection - no special MCP client needed for these basic checks.

**List available tools** to confirm your subscription has access:

```bash theme={"system"}
curl -X POST https://gc-prod-instance.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'
```

You should see a JSON-RPC response with a `result.tools` array containing tool definitions:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "getAccountBalance",
        "description": "Get current balance for a bank account",
        "inputSchema": {
          "type": "object",
          "properties": {
            "accountId": {"type": "string", "pattern": "^ACC-[0-9]{6}$"}
          },
          "required": ["accountId"]
        }
      },
      {
        "name": "getCustomerProfile",
        "description": "Retrieve customer information",
        "inputSchema": {...}
      }
    ]
  },
  "id": 1
}
```

If you see an empty tools array or a 401 error, check your subscription key in the admin portal.

**Invoke a tool** to test the full request/response cycle:

```bash theme={"system"}
curl -X POST https://gc-prod-instance.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: a1b2c3d4e5f6g7h8i9j0" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "getAccountBalance",
      "arguments": {"accountId": "ACC-789456"}
    },
    "id": 2
  }'
```

A successful response looks like:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"accountId\":\"ACC-789456\",\"currentBalance\":15234.50,\"availableBalance\":14800.00,\"currency\":\"USD\"}"
      }
    ]
  },
  "id": 2
}
```

If you see errors, check the `error.code` and `error.message` fields. Common issues: `-32602` (invalid parameters), `-32001` (authentication failure), `-32000` (backend API error).

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 unauthorized">
    **Cause**: Invalid or expired credentials

    **Solution**:

    * Verify subscription key is correct
    * Check JWT token hasn't expired
    * Ensure token audience matches Grand Central instance
  </Accordion>

  <Accordion title="429 rate limit exceeded">
    **Cause**: Too many requests in time window

    **Solution**:

    * Implement exponential backoff
    * Check your rate limits in the admin portal
    * Adjust limits through the portal if needed
  </Accordion>

  <Accordion title="No tools returned">
    **Cause**: No tools enabled for your subscription

    **Solution**:

    * Log into the admin portal and enable tools from the API catalog
    * Verify your subscription key has access to the tools you enabled
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tool discovery" icon="magnifying-glass" href="/mcp/capabilities/tool-discovery">
    Learn how tool discovery works
  </Card>

  <Card title="Authentication" icon="key" href="/mcp/capabilities/authentication">
    Understand authentication in detail
  </Card>

  <Card title="Rate limiting" icon="gauge" href="/mcp/capabilities/rate-limiting">
    Learn about rate limits and quotas
  </Card>

  <Card title="Best practices" icon="star" href="/mcp/advanced/best-practices">
    Follow patterns for reliable integrations
  </Card>
</CardGroup>