Developers

MCP Server

FinkMesh MCP is a token-authenticated JSON-RPC endpoint at /api/mcp. Tool access is filtered by API token or OAuth scopes, and write tools route through the same public API idempotency, readiness, quota, and audit contracts.

API-token MCP is available for developers. OAuth-backed MCP is now scaffolded for marketplace connector testing, but should stay limited to read/debug tools and support ticket creation until connector review is complete.

OAuth Marketplace Foundation

OAuth MCP uses public PKCE clients, a FinkMesh consent screen, audience-bound bearer tokens, and token revocation. The authorization server and protected resource metadata are exposed for connector discovery.

/.well-known/oauth-protected-resource
Protected resource metadata
/.well-known/oauth-authorization-server
Authorization server metadata
/api/oauth/mcp/register
Dynamic client registration
/api/oauth/mcp/authorize
Authorization + consent
/api/oauth/mcp/token
PKCE token exchange
/api/oauth/mcp/revoke
Token revocation

Connection

POST https://www.finkmesh.com/api/mcp
Authorization: Bearer fmsh_live_...
Content-Type: application/json
MCP-Protocol-Version: 2025-11-25

OAuth connector clients use Authorization: Bearer fmsh_mcp_...after completing the PKCE flow.

Start with initialize, then call tools/list. Clients may call tools/call only for tools visible to the token.

Write Safety

finkmesh.workflow.run and finkmesh.support.create_ticket require an idempotencyKey argument. Reusing the same key with the same body safely replays the existing public API response; changing the body returns a conflict.

MCP tools never return credential secrets, OAuth tokens, bearer headers, webhook secrets, or raw node input/output payloads.

Tools

finkmesh.contextworkspace:readInspect token, user, workspace, and organization context.
finkmesh.usage.getruns:readRead usage, plan limits, and entitlements.
finkmesh.workflows.listworkflows:readList workflow summaries without raw graph nodes.
finkmesh.workflows.getworkflows:readFetch one curated workflow summary.
finkmesh.workflow.readinessworkflows:readEvaluate publish/run/webhook/schedule readiness.
finkmesh.workflow.runworkflows:runQueue a run. Requires idempotencyKey.
finkmesh.runs.listruns:readList redacted run summaries.
finkmesh.runs.getruns:readFetch redacted run detail and debug metadata.
finkmesh.connections.listconnections:readList connection health metadata without secrets.
finkmesh.webhooks.listwebhooks:readList outbound webhook endpoints without secrets.
finkmesh.support.create_ticketsupport:writeCreate a support ticket. Requires idempotencyKey.

Structured Results Roadmap

The current developer-preview tools return serialized JSON in MCP text content for broad client compatibility. The OAuth marketplace track should return both backwards-compatible text and structuredContent with outputSchema for each tool, so assistant and IDE clients can parse results without re-reading JSON strings.

{
  "content": [
    {
      "type": "text",
      "text": "{\"ok\":true,\"action\":\"api_run\"}"
    }
  ],
  "structuredContent": {
    "ok": true,
    "action": "api_run",
    "blockingIssueCount": 0
  }
}

Manifest

GET https://www.finkmesh.com/api/mcp

{
  "protocolVersion": "2025-11-25",
  "serverInfo": {
    "name": "finkmesh",
    "version": "2026-07-01"
  },
  "endpoint": "/api/mcp"
}

Initialize

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

Initialize Result

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": {
      "name": "finkmesh",
      "version": "2026-07-01"
    },
    "capabilities": {
      "tools": {}
    }
  }
}

List Tools

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

List Tools Result

{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "result": {
    "tools": [
      {
        "name": "finkmesh.workflow.readiness",
        "description": "Evaluate workflow readiness.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "workflowId": { "type": "string" },
            "action": { "type": "string" }
          }
        }
      }
    ]
  }
}

Context Tool

{
  "jsonrpc": "2.0",
  "id": "context-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.context",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": "context-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"workspace\":{\"id\":\"wsp_...\",\"name\":\"Launch Smoke\"},\"organization\":{\"id\":\"org_...\"}}"
      }
    ]
  }
}

List Workflows Tool

{
  "jsonrpc": "2.0",
  "id": "workflows-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.workflows.list",
    "arguments": { "limit": 10 }
  }
}

{
  "jsonrpc": "2.0",
  "id": "workflows-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[{\"id\":\"wf_...\",\"name\":\"Lead routing\",\"active\":true}],\"pagination\":{\"nextCursor\":null}}"
      }
    ]
  }
}

Get Workflow Tool

{
  "jsonrpc": "2.0",
  "id": "workflow-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.workflows.get",
    "arguments": { "workflowId": "wf_123" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "workflow-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"wf_123\",\"name\":\"Lead routing\",\"active\":true,\"nodeCount\":4}"
      }
    ]
  }
}

Check Readiness

{
  "jsonrpc": "2.0",
  "id": "ready-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.workflow.readiness",
    "arguments": {
      "workflowId": "wf_123",
      "action": "api_run"
    }
  }
}

Readiness Result

{
  "jsonrpc": "2.0",
  "id": "ready-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"ok\":true,\"action\":\"api_run\",\"blockingIssueCount\":0,\"warningCount\":0}"
      }
    ]
  }
}

List Runs Tool

{
  "jsonrpc": "2.0",
  "id": "runs-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.runs.list",
    "arguments": { "limit": 10, "status": "success" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "runs-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[{\"id\":\"run_...\",\"status\":\"success\",\"workflowId\":\"wf_...\"}],\"pagination\":{\"nextCursor\":null}}"
      }
    ]
  }
}

Get Run Tool

{
  "jsonrpc": "2.0",
  "id": "run-detail-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.runs.get",
    "arguments": { "runId": "run_123" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "run-detail-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"run_123\",\"status\":\"success\",\"nodeResults\":[]}"
      }
    ]
  }
}

List Webhooks Tool

{
  "jsonrpc": "2.0",
  "id": "webhooks-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.webhooks.list",
    "arguments": { "limit": 10 }
  }
}

{
  "jsonrpc": "2.0",
  "id": "webhooks-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\":[{\"id\":\"wh_...\",\"status\":\"active\",\"secretPreview\":\"whsec_...xyz123\"}],\"pagination\":{\"nextCursor\":null}}"
      }
    ]
  }
}

Run Workflow

{
  "jsonrpc": "2.0",
  "id": "run-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.workflow.run",
    "arguments": {
      "workflowId": "wf_123",
      "triggerData": { "source": "mcp" },
      "idempotencyKey": "mcp-run-123"
    }
  }
}

Run Workflow Result

{
  "jsonrpc": "2.0",
  "id": "run-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"runId\":\"run_...\",\"status\":\"queued\",\"links\":{\"run\":\"/api/v1/runs/run_...\"}}"
      }
    ]
  }
}

Create Support Ticket Tool

{
  "jsonrpc": "2.0",
  "id": "ticket-1",
  "method": "tools/call",
  "params": {
    "name": "finkmesh.support.create_ticket",
    "arguments": {
      "title": "API question",
      "description": "Need help with readiness.",
      "priority": "normal",
      "idempotencyKey": "mcp-ticket-123"
    }
  }
}

Support Ticket Result

{
  "jsonrpc": "2.0",
  "id": "ticket-1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"tkt_...\",\"status\":\"open\",\"title\":\"API question\"}"
      }
    ]
  }
}

Error Response

{
  "jsonrpc": "2.0",
  "id": "run-1",
  "error": {
    "code": -32000,
    "message": "Token lacks required scope: workflows:run."
  }
}