Inbound MCP Tools

Inbound MCP Tools allow you to connect external APIs, third-party platforms, and internal business systems directly into Finqu AI. By registering an external Model Context Protocol (MCP) server, your custom tools become available across all Finqu AI surfaces:

Success Agent can call your tools interactively during merchant chat.
Workers (Analyst, Planner, Executor) can call your tools during autonomous background runs.
Playbooks (Playbooks) can invoke your tools within structured execution steps.

Inbound vs Outbound MCP: - Inbound MCP Tools (this guide): Bring external tools into Finqu AI so Finqu’s agents can query your systems. - Admin MCP (Admin MCP Guide): Bring external agents (Claude, Cursor, custom agents) outbound to operate Finqu’s store tools.

Connection Specifications

Finqu supports standard MCP connection specifications for inbound servers.

Transports

Transport	Protocol Identifier	Description
Streamable HTTP	`streamable_http`	Standard HTTP POST transport with streaming chunk support. Recommended for all modern cloud deployments
Server-Sent Events	`sse`	Persistent HTTP connection using SSE streams for tool discovery and responses

Authentication Schemes

Configure how Finqu authenticates with your external MCP endpoint:

Scheme	`auth_type`	Configuration Payload	Notes
Bearer Token	`bearer`	`{ "token": "YOUR_SECRET_TOKEN" }`	Injected into the `Authorization: Bearer <token>` header on every MCP request
OAuth 2.0	`oauth2`	`{ "client_id", "client_secret", "token_url", "scopes" }`	Finqu executes client credentials or authorization code flow to obtain and rotate access tokens
None	`none`	`{}`	No authentication headers added. Useful for development tunnels (e.g. ngrok) or private VPCs

Tool Authoring Standards

Finqu AI agents rely on precise schemas and deterministic outputs to decide when and how to call your tools.

1. Tool schema design

Descriptive tool names: Use lowercase snake_case indicating action and entity (e.g. check_warehouse_inventory, create_crm_ticket).
Semantic descriptions: Explain what the tool does, when the model should invoke it, and what constraints apply.
Type annotations: Use valid JSON Schema for all input properties (string, integer, number, boolean, array, object).
Required fields: Always specify required fields in the schema’s required array.

Example tool schema


{
  "name": "check_warehouse_stock",
  "description": "Check real-time stock levels and shelf location for an SKU in the central warehouse.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sku": {
        "type": "string",
        "description": "The merchant product SKU to look up (e.g. 'SHIRT-BLUE-M')"
      },
      "warehouse_code": {
        "type": "string",
        "description": "Optional warehouse identifier. Defaults to 'CENTRAL'",
        "default": "CENTRAL"
      }
    },
    "required": ["sku"]
  }
}

2. Output formats

Return clean JSON payloads serialized as MCP text content. Avoid dumping unparsed HTML or giant unstructured logs.


{
  "content": [
    {
      "type": "text",
      "text": "{\"sku\":\"SHIRT-BLUE-M\",\"available_quantity\":42,\"reserved_quantity\":3,\"shelf\":\"A-12-04\",\"status\":\"in_stock\"}"
    }
  ]
}

3. Latency and timeouts

Finqu AI enforces a 30-second execution timeout per tool call.
Tools should complete within 1 to 5 seconds to keep agent interactions responsive.
For long-running asynchronous jobs, return a pending job status immediately (e.g. {"job_id": "xyz", "status": "processing"}) and provide a status-checking tool for follow-up verification.

4. Error reporting

If your tool encounters an error, return an MCP error response with isError: true and an informative message:


{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "SKU 'INVALID-SKU' was not found in the warehouse database. Verify the SKU format."
    }
  ]
}

Admin Registration


{
  "name": "Acme Warehouse ERP",
  "url": "https://mcp.acme-logistics.com/mcp",
  "protocol": "streamable_http",
  "auth_type": "bearer",
  "auth_config": {
    "token": "sk_live_98a7sd8f7a6sdf"
  },
  "enabled": true
}

Registration fields

Field	Type	Required	Description
`name`	string	Yes	Unique display name for the MCP server in Finqu admin
`url`	string	Yes	Fully qualified HTTPS URL to the MCP server endpoint
`protocol`	string	Yes	`streamable_http` or `sse`
`auth_type`	string	Yes	`bearer`, `oauth2`, or `none`
`auth_config`	object	Yes	Authentication parameters (tokens, credentials, or empty object)
`enabled`	boolean	Yes	Whether tools from this server are active

Once registered, Finqu probes the endpoint using tools/list and imports the discovered tool definitions into the merchant’s AI tool registry.

Building an Inbound MCP Server (TypeScript)

Here is a complete, deployable MCP server built with @modelcontextprotocol/sdk and express implementing Streamable HTTP:


import express from "express";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHttpServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
const app = express();
app.use(express.json());
 
// Initialize MCP Server instance
const server = new Server({ name: "acme-warehouse-tools", version: "1.0.0" }, { capabilities: { tools: {} } });
 
// 1. Advertise available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_external_inventory",
        description: "Fetch live warehouse stock counts and pallet locations for an SKU.",
        inputSchema: {
          type: "object",
          properties: {
            sku: { type: "string", description: "Product SKU" },
          },
          required: ["sku"],
        },
      },
    ],
  };
});
 
// 2. Handle tool invocation
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
 
  if (name === "get_external_inventory") {
    const sku = String(args?.sku);
 
    // Simulated ERP database lookup
    const inventoryData = {
      sku,
      quantity_on_hand: 120,
      allocated: 15,
      available: 105,
      location: "Aisle 4, Bay 12",
    };
 
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(inventoryData),
        },
      ],
    };
  }
 
  throw new Error(`Unknown tool: ${name}`);
});
 
// 3. Expose Streamable HTTP endpoint
app.post("/mcp", async (req, res) => {
  // Verify Bearer token authorization
  const authHeader = req.headers.authorization;
  if (authHeader !== "Bearer secret-token-123") {
    return res.status(401).json({ error: "Unauthorized" });
  }
 
  const transport = new StreamableHttpServerTransport(req, res);
  await server.connect(transport);
});
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Inbound MCP server listening on port ${PORT}`);
});

Using Custom Tools Across Finqu AI

Once an inbound MCP server is registered, its tools can be assigned to different AI workflows:

In Success Agent chat

In the Finqu admin assistant, merchants can toggle external tool groups on or off. When enabled, the Success Agent automatically invokes your tools to answer merchant questions (e.g. “How many units of SKU-100 remain in the central warehouse?”).

In Workers

Whitelisting external tools on a Worker grants background agents access to outside systems:


{
  "slug": "warehouse-sync-analyst",
  "name": "Warehouse Sync Analyst",
  "type": "analyst",
  "system_prompt_extension": "Compare warehouse inventory against Finqu catalog levels. Flag any discrepancies over 5 units.",
  "tool_names": ["search_products", "get_product_inventory", "get_external_inventory"]
}

In Playbooks

Reference external tools within individual Playbook steps to automate multi-system operations:


{
  "id": "fetch_external_stock",
  "name": "Check External Warehouse",
  "worker_type": "analyst",
  "instructions": "Call get_external_inventory for each product SKU found in {{steps.scan_orders.flagged_skus}}.",
  "allowed_tools": ["get_external_inventory"],
  "output_variable": "warehouse_counts"
}

Next steps

Authoring Workers — Configure background agents with custom tool whitelists
Authoring Playbooks — Orchestrate multi-system workflows with Playbook steps
Guidelines — Define global rules and guardrails for how agents use tools
Admin MCP Overview — Connect your own external agents to Finqu store tools