MCP Workflows

Summary

An MCP workflow combines an AI client with the Eigenn records that its credential permits. Start with a read-only task. Examine every tool that the client shows. Add write access only after you prove the review process.

Capabilities

An MCP client can retrieve scoped Eigenn records, prepare analysis for review, and invoke selected write tools. It can also discover active product workflows, request a run, and poll its status with the required permissions. Client confirmations and any workflow approval steps must be configured; MCP does not automatically enforce an organization-wide review policy.

Prerequisites

You need a valid Eigenn account with access to the relevant data and the ability to create API credentials or OAuth applications with well-defined read or write scopes. Your AI client must be compatible with Eigenn's MCP endpoint. For any write capability, you should have tested access on non-production or reversible data.

Concepts

Choose a Bounded Task

Good first workflows include:

• Prepare a financial health summary
• Rank overdue invoices for follow-up
• Analyze expense patterns
• Summarize customer payment context
• Investigate transactions that need review

Do not start with an open-ended instruction such as one to manage all finance operations. Define the records, the time period, the output, the reviewer, and the actions that are out of bounds.

Product Workflow Boundary

Use Workflows to create, edit, and promote definitions. MCP can list active definitions with workflows_list, start a permitted promoted definition with workflows_execute, and read a known run with workflows_get_run. List and status require workflows.read; execution requires both workflows.read and workflows.write. The API is another execution surface; see Workflows API.

An analysis conversation does not become a product run until an execution tool is called. The workflow list includes at most 50 active definitions and shows draft-derived hints; it does not guarantee a runnable promoted version or provide a full run-history list.

Workflow

1. Create the Credential

1. Open Settings → Developer.
2. Have an eligible Owner create a restricted API key, or configure an OAuth application with the required grants and callback URL. See Authentication for role and plan requirements.
3. Grant only the read scopes needed by the task.
4. Store a key in a server-side secret manager when the client needs one.

Example read-only grants:

A valid credential needs at least one compatible MCP scope. Domain tools need their specific grants; common context/discovery tools can appear without a separate resource grant. The restricted-key picker does not offer workflow scopes, and its Write selection does not include Read. Confirm the actual credential before expecting workflow tools.

2. Connect the Client

Use the remote endpoint:

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

Use the MCP connection guide for current VS Code, Cursor, Claude, and optional bridge configuration. Configure the OAuth client and exact callback URL, or use a client that securely sends a bearer token. A server URL alone is not a completed authentication setup.

After connection, call context_get and confirm teamId, server time, and the timezone used for the task. If timezone information is absent, specify it explicitly in the analysis request.

3. Examine the Available Tools

Before you send business data to a prompt:

1. Open the client's tool inspector.
2. Record the available Eigenn tools.
3. Confirm that there are no write tools outside the task.
4. Examine resources such as team information, categories, or tags.
5. Choose a built-in prompt or write a bounded instruction.

Built-in prompt templates include:

• financial_health_check
• invoice_followup
• expense_analysis
• customer_insights

Tool availability follows scopes. Prompts are templates, not completed analyses, and do not grant the tools they mention. search_tools can find registered reads and writes; call_tool dispatches reads only. The remote endpoint does not promise the generated api_ tool collection used in other contexts.

4. State the Review Contract

Include these constraints in the task:

• The exact date range and team
• The records that the client can read
• The format of the answer
• The calculations that need source citations
• The actions that need a person
• The actions that you prohibit

Example:

Review unpaid and overdue invoices for this team.
Use invoice and customer read tools only.
Return a table with invoice ID, customer, amount, due date, and suggested next step.
Do not change records or draft customer messages.
Flag missing data instead of guessing.

5. Confirm the Output

The reviewer must:

1. Compare record IDs with Eigenn.
2. Confirm currencies and date ranges.
3. Separate missing data from zero values.
4. Check calculations against source records.
5. Reject recommendations that need unavailable context.
6. Record the approved next action outside the model response.

6. Add a Write Scope Only When Needed

Some MCP domains expose customer, invoice, tracker, or workflow-execution writes. The server does not wrap every tool call in a universal approval gate.

Before you grant a write scope:

• Turn on the client's confirmation feature
• Limit the credential to one resource
• Test against non-production or reversible data
• Make the write idempotent where the operation supports it
• Check the record that results in Eigenn
• Keep a separate read-only credential for analysis

7. Start a Product Workflow When Required

1. Grant workflows.read and inspect workflows_list. It lists up to 50 active definitions; its runnable flag only says the draft parses.
2. Confirm the intended definition has a promoted version and permits external execution. Check its trigger type and required inputs in Eigenn.
3. Use a credential with workflows.read and workflows.write and permission to write the workflow's namespace. The execution request validates both scopes and applicable product permissions.
4. Call workflows_execute with workflowId, matching triggerType, and team-scoped triggerData. The tool supports manual, webhook, invoice_overdue, and payment_failed trigger types; it does not accept every possible product trigger.
5. Supply an idempotencyKey of 1–255 characters for the intended run. Reuse it only for an exact logical retry; it is separate from the HTTP replay header.
6. Retain the returned executionId and poll workflows_get_run. A queued response means accepted, not finished. waiting can mean a person must approve an action.
7. Inspect tool errors and final state. Check the resulting records in Eigenn before reporting completion. A missing/inactive/unpublished workflow, disabled API trigger, namespace restriction, or invalid team input can refuse the run.

Behavior specification

Troubleshoot

The connection returns 403

At connection time, check for a valid credential with an MCP-compatible scope. During a tool call, also inspect operation-specific permissions and error details; adding a scope does not resolve every denial.

A necessary tool does not appear

Compare the tool's resource with the key or the OAuth grant. Reconnect after you change the scopes.

The client can write when it must only read

Revoke or rotate the credential with read-only scopes. Client prompts are not an access-control boundary.

The answer lacks source context

Ask for record IDs and dates in the output. Then check them in Eigenn before you approve an action.

Diagrams

Screenshots

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

Verification

1. Log into Eigenn and open the API credential management page; verify the created credential only grants the required read scopes.
2. Using your AI client, connect to the MCP endpoint and confirm only allowed tools are listed; record the tool list.
3. Attempt the defined bounded task and compare output against actual records for accuracy, including IDs, dates, and values.
4. For a controlled write, verify the client confirmation policy and resulting record. Do not infer confirmation from MCP scopes alone.
5. On an isolated promoted workflow, verify list/status scope access, execute with both scopes, retain the execution ID, retry the same logical run key, and poll to a terminal or explicitly waiting state. Check refused runs with mismatched triggers and inaccessible inputs.
6. Remove or rotate any credential that unintentionally grants broader access and confirm revoked rights using tool inspector and attempted client actions.
7. Use troubleshooting steps to diagnose and remediate any mismatches between intent and actual available actions.

Related

Related Pages

• MCP
• Authentication
• Workflows
• Workflows API