Connecting Agents to Admin MCP

{
  "mcpServers": {
    "finqu-admin": {
      "url": "https://mcp.finqu.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "finqu-admin": {
      "url": "https://mcp.finqu.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

---
description: Rules for using Finqu Admin MCP tools
globs: *
alwaysApply: true
---
 
# Finqu Admin MCP Rules
 
When interacting with the Finqu Admin MCP server:
 
1. **Session initialization**:
   - Call `get_profile` to verify merchant context and granted scopes.
   - Call `list_channels` before issuing any channel-scoped tool. Store `channel_id` for subsequent calls.
 
2. **Channel requirements**:
   - Theme tools, navigation tools, and page tools require a `webstore` channel type.
   - Do not pass non-webstore channel IDs to theme or storefront tools.
 
3. **Safety and confirmation**:
   - Always confirm destructive operations with the user before calling write tools (e.g., deleting product variants,
     changing prices, unpublishing items, modifying theme files).
   - Display a preview of proposed changes and wait for user confirmation.
 
4. **Error handling**:
   - Inspect error responses with `{ "status": "error", "response": { "code", "message", "suggestions" } }`.
   - If a tool reports `revision_mismatch` or `release_missing`, refresh the state before retrying.

{
  "servers": {
    "finqu": {
      "type": "http",
      "url": "https://mcp.finqu.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "finqu": {
      "httpUrl": "https://mcp.finqu.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "finqu": {
      "type": "streamableHttp",
      "url": "https://mcp.finqu.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHttpClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
interface FinquChannel {
  id: number;
  name: string;
  type: string;
  store: Record<string, unknown>;
}
 
interface FinquProfile {
  user: { id: number; name: string; email: string };
  merchant: { id: number; name: string; hostname: string; currency_id: number };
  scopes: string[];
}
 
/**
 * Discover OAuth authorization server endpoints using RFC 9728 and RFC 8414.
 */
async function discoverOAuthMetadata(mcpUrl: string): Promise<{
  authorizationEndpoint: string;
  tokenEndpoint: string;
}> {
  // Step 1: Probe MCP endpoint for RFC 9728 resource metadata
  const probeResponse = await fetch(mcpUrl, { method: "GET" });
  const authHeader = probeResponse.headers.get("www-authenticate") || "";
 
  const match = authHeader.match(/resource_metadata="([^"]+)"/);
  const resourceMetadataUrl = match ? match[1] : "https://mcp.finqu.com/.well-known/oauth-protected-resource/mcp";
 
  // Step 2: Fetch protected resource metadata
  const resourceRes = await fetch(resourceMetadataUrl);
  const resourceData = await resourceRes.json();
  const authServerBase = resourceData.authorization_servers?.[0] || "https://account.finqu.com";
 
  // Step 3: Fetch RFC 8414 authorization server metadata
  const serverMetaRes = await fetch(`${authServerBase}/.well-known/oauth-authorization-server`);
  const serverMeta = await serverMetaRes.json();
 
  return {
    authorizationEndpoint: serverMeta.authorization_endpoint,
    tokenEndpoint: serverMeta.token_endpoint,
  };
}
 
/**
 * Initialize and run a Finqu Admin MCP agent session.
 */
async function runAdminAgent(accessToken: string) {
  const mcpUrl = new URL("https://mcp.finqu.com/mcp");
 
  // Initialize Streamable HTTP transport with Bearer token
  const transport = new StreamableHttpClientTransport(mcpUrl, {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    },
  });
 
  const client = new Client({ name: "finqu-custom-agent", version: "1.0.0" }, { capabilities: {} });
 
  await client.connect(transport);
  console.log("Connected to Finqu Admin MCP");
 
  // Step 1: Discover available tools
  const toolsResult = await client.listTools();
  console.log(`Discovered ${toolsResult.tools.length} admin tools`);
 
  // Step 2: Get merchant profile and active scopes
  const profileResult = await client.callTool({
    name: "get_profile",
    arguments: {},
  });
  const profile = profileResult.content[0].text ? (JSON.parse(profileResult.content[0].text) as FinquProfile) : null;
 
  console.log(`Authenticated as merchant: ${profile?.merchant.name} (ID: ${profile?.merchant.id})`);
  console.log(`Granted scopes: ${profile?.scopes.join(", ")}`);
 
  // Step 3: Discover sales channels
  const channelsResult = await client.callTool({
    name: "list_channels",
    arguments: {},
  });
  const channelsPayload = channelsResult.content[0].text
    ? (JSON.parse(channelsResult.content[0].text) as { merchant_id: number; channels: FinquChannel[] })
    : { merchant_id: 0, channels: [] };
 
  const webstoreChannel = channelsPayload.channels.find((c) => c.type === "webstore");
  const defaultChannelId = webstoreChannel?.id || channelsPayload.channels[0]?.id;
 
  console.log(`Selected default channel ID: ${defaultChannelId} (${webstoreChannel?.name})`);
 
  // Example tool call requiring channel_id
  if (defaultChannelId) {
    const categoriesResult = await client.callTool({
      name: "list_categories",
      arguments: {
        channel_id: defaultChannelId,
        limit: 10,
      },
    });
    console.log("Categories response:", categoriesResult.content[0].text);
  }
 
  await client.close();
}
 
// Example invocation
const token = process.env.FINQU_ACCESS_TOKEN || "YOUR_ACCESS_TOKEN";
runAdminAgent(token).catch(console.error);

pip install mcp httpx

import asyncio
import os
import re
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
 
MCP_URL = "https://mcp.finqu.com/mcp"
 
async def discover_oauth_endpoints(mcp_url: str):
    """Discover OAuth 2.0 endpoints using RFC 9728 and RFC 8414."""
    async with httpx.AsyncClient() as http:
        # Step 1: Probe unauthenticated endpoint
        probe = await http.get(mcp_url)
        auth_header = probe.headers.get("www-authenticate", "")
 
        match = re.search(r'resource_metadata="([^"]+)"', auth_header)
        meta_url = (
            match.group(1)
            if match
            else "https://mcp.finqu.com/.well-known/oauth-protected-resource/mcp"
        )
 
        # Step 2: Fetch protected resource metadata
        resource_res = await http.get(meta_url)
        resource_data = resource_res.json()
        auth_server = resource_data.get("authorization_servers", ["https://account.finqu.com"])[0]
 
        # Step 3: Fetch authorization server metadata
        server_meta_res = await http.get(f"{auth_server}/.well-known/oauth-authorization-server")
        server_meta = server_meta_res.json()
 
        return {
            "authorization_endpoint": server_meta.get("authorization_endpoint"),
            "token_endpoint": server_meta.get("token_endpoint"),
        }
 
async def run_admin_session(access_token: str):
    """Connect to Finqu Admin MCP, run startup sequence, and invoke tools."""
    headers = {
        "Authorization": f"Bearer {access_token}"
    }
 
    async with streamable_http_client(MCP_URL, headers=headers) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            print("Connected to Finqu Admin MCP")
 
            # 1. Discover tools
            tools_response = await session.list_tools()
            print(f"Discovered {len(tools_response.tools)} admin tools")
 
            # 2. Get profile
            profile_res = await session.call_tool("get_profile", arguments={})
            print("Profile output:", profile_res.content[0].text)
 
            # 3. List channels
            channels_res = await session.call_tool("list_channels", arguments={})
            print("Channels output:", channels_res.content[0].text)
 
            # Store channel_id for subsequent calls
            import json
            channel_data = json.loads(channels_res.content[0].text)
            channels = channel_data.get("channels", [])
            webstore = next((c for c in channels if c.get("type") == "webstore"), None)
            channel_id = webstore["id"] if webstore else (channels[0]["id"] if channels else None)
 
            if channel_id:
                print(f"Using channel_id: {channel_id}")
                products_res = await session.call_tool(
                    "search_products",
                    arguments={"channel_id": channel_id, "limit": 5}
                )
                print("Products search result:", products_res.content[0].text)
 
if __name__ == "__main__":
    token = os.environ.get("FINQU_ACCESS_TOKEN", "YOUR_ACCESS_TOKEN")
    asyncio.run(run_admin_session(token))