MCP

Summary

Eigenn has a remote Model Context Protocol endpoint for scoped finance retrieval and selected writes:

https://api.eigenn.io/v1/mcp

The endpoint uses Streamable HTTP. OAuth metadata identifies authorization/token endpoints, but discovery alone does not register a client or prove a complete login flow. Use a registered OAuth application or a client that can securely supply an API bearer token.

Capabilities

Scope Controls

The MCP endpoint accepts a connection only when the credential includes at least one MCP-compatible scope. Domain tools depend on resource scopes. Context/discovery tools and static categories are available once the connection is authorized; their presence does not grant access to other finance records.

Examples include:

• search.read
• customers.read and customers.write
• invoices.read and invoices.write
• transactions.read
• reports.read
• bank-accounts.read
• documents.read
• tracker-entries.read and tracker-entries.write
• teams.read
• workflows.read and workflows.write

A 403 at connection time means the credential lacks a compatible MCP scope. Later tool calls can also fail because of operation-specific permissions. A 401 can mean an invalid credential, inaccessible team, or empty effective grant. Viewer membership removes write scopes from user-linked credentials.

Use a read-only key or OAuth grant for analysis workflows. Add a write scope only when the client must do that specific write.

Tools, Resources, and Prompts

The granted scopes control which of these tools Eigenn shows:

• search of finance records
• customers
• invoices, products, templates, and recurring invoices
• transactions and categories
• bank accounts
• documents and inbox items
• reports
• tags
• team context
• tracker projects, entries, and timers
• workflow discovery, execution, and run status

Static or team-scoped resources can include transaction categories, tags, and team information. Built-in prompts cover financial health checks, invoice follow-up, expense analysis, and customer insights.

Use the client's tool inspector or search_tools to discover the current registry. search_tools returns up to 25 results by default, with a maximum requested limit of 100; it can include write tools. call_tool only dispatches tools marked read-only and refuses writes, which must be invoked directly.

The public HTTP endpoint does not expose the generated api_ read-tool collection used by other application contexts. Do not assume every internal product action is available. context_get reports the current team, server time, and available locale/timezone information; use it before interpreting relative dates.

Prerequisites

Use a client with Streamable HTTP support, or an appropriate local bridge. Authentication requires either securely configured bearer credentials or a compatible OAuth flow. API-key creation requires an owner with eligible plan access; see Authentication.

For OAuth, configure an application with the client's exact callback URL and requested scopes. Public clients require S256 PKCE. Discovery does not advertise dynamic client registration, so do not assume a URL-only entry will obtain a client ID. Workflow scopes are not offered by the current restricted-key picker; do not broaden a credential to All without reviewing the added access.

Concepts

Product Workflow Boundary

MCP exposes three workflow tools:

The list has no pagination input and is not a complete execution-history browser. Its trigger, apiEnabled, and runnable fields describe the stored draft; runnable means the draft parses, not that a promoted version exists or execution is authorized. Starting a run checks the promoted snapshot, active state, writable namespace, trigger type, team-bound inputs, and API-enable setting. Listing a workflow does not prove those checks will pass.

Build, edit, and promote definitions in Workflows. Use workflows_get_run to poll a known run; waiting means it is paused, often for approval, rather than failed. The tools do not create or edit workflow definitions.

MCP can still support a bounded process that AI helps. Examples are an invoice follow-up summary and an examination of unusual transactions. The process uses only the records that its scopes cover.

Workflow

Connect a Client

For VS Code, place a native HTTP entry in .vscode/mcp.json. Configure authentication separately. See the VS Code MCP setup guide.

{
  "servers": {
    "eigenn": {
      "type": "http",
      "url": "https://api.eigenn.io/v1/mcp"
    }
  }
}

Cursor also supports a native remote URL entry; see Cursor MCP configuration for bearer headers or static OAuth credentials. Claude supports remote custom connectors; configure the URL and application credentials through its custom connector setup. Its remote connector runs from cloud infrastructure, so it cannot directly reach a localhost-only test stack.

For a client configuration that uses a local stdio bridge, the existing mcp-remote connection shape is:

{
  "mcpServers": {
    "eigenn": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.eigenn.io/v1/mcp"
      ]
    }
  }
}

The equivalent command is:

npx -y mcp-remote https://api.eigenn.io/v1/mcp

The bridge command still needs compatible OAuth client registration/configuration; it is not proof of automatic login. When OAuth is configured, complete consent and verify the selected team with context_get. A bearer-capable client can instead send the same Authorization header as REST. Keep credentials in the client's secret configuration, not checked-in JSON.

Behavior specification

Approval Boundary

MCP scopes are the server-side access control. The endpoint does not add a universal human-approval step around every tool call.

For sensitive work:

1. Grant read scopes first.
2. Turn on the client's own confirmation controls.
3. Make a person examine each proposed customer, invoice, cash, or ledger change.
4. Grant a write scope only for the bounded action.
5. Examine the Eigenn record after the action runs.

Do not describe a client as read-only when it exposes customer, invoice, tracker, or workflow execution tools. A workflow may impose its own approval steps, but that is separate from a universal MCP confirmation gate.

MCP protocol messages are HTTP POSTs and can consume the REST write-rate bucket even for read-only tools. Handle HTTP failures separately from a tool result with isError: true. A successful HTTP response does not prove the requested action succeeded.

For workflows_execute, idempotencyKey is a tool argument of 1–255 characters, distinct from the optional HTTP Idempotency-Key header. Reuse the same argument for retries of the same intended run and retain the execution ID; changing trigger data while reusing the key does not request a new run. A queued acknowledgement is not proof of completion.

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

Troubleshoot

The client cannot discover authentication

Confirm the endpoint, transport, registered client ID, exact callback URL, and requested scopes. Metadata discovery is only one part of authentication. Use a local client for a localhost stack; cloud-hosted connectors need a reachable server.

The connection returns 401

Authenticate again. Then confirm that the OAuth grant or the API key belongs to an accessible team.

The connection returns 403

Create or update a restricted credential with at least one compatible scope. Add only the resource scopes that the workflow needs.

A tool is not present

Compare the requested operation with the granted scopes. Eigenn does not register the tools whose resources are outside the grant.

A product workflow operation is not present

Check workflows.read first. workflows_execute additionally requires workflows.write; a write-only grant does not register it. Build/edit operations are absent by design. If execution is refused, inspect the returned reason and the promoted workflow rather than retrying blindly.

1. Check that your client can connect to the Eigenn MCP endpoint at https://api.eigenn.io/v1/mcp. Expected: Client initiates connection and prompts for OAuth if required.
2. Grant only a read scope and attempt to use a write tool. Expected: Client does not show or enable the write tool, or the operation fails with an authorization error.
3. Connect using a credential without any compatible scope. Expected: Connection attempt returns HTTP 403.
4. Connect using an invalid or missing credential or incorrect team context. Expected: Connection attempt returns HTTP 401.
5. After connecting with appropriate scopes, view the available tools in the client tool inspector. Expected: Domain tools match the grant, alongside common context/discovery tools. With workflows.read, verify list and run-status tools; add workflows.write only for a controlled execution fixture.

Related

Related Pages

• MCP Workflows
• Authentication
• Developer Platform
• Workflows API