Affino MCP — Agent Access to Your Affino Instance

Affino MCP has three moving parts. Understanding how they fit together makes the configuration steps below obvious instead of arbitrary.

The API Profile lives in Affino and acts as the contract between an agent workload and your instance. It defines which object families the agent can touch and on which operations (read, write, or both). The profile issues an API Key and an API Secret that the agent uses to identify the workload. The profile is not a user. It does not own records. It defines a capability envelope.

The user session lives in Affino's existing authentication stack. When a person logs in through the normal Hub or API login, Affino issues an AccessToken tied to their user record. That token is a plain UUID looked up against Affino's active-session store (APIProfileActiveSession). Agents do not invent identity. They borrow an existing, valid user session.

The MCP connection lives on the agent side. When the agent opens an MCP channel to your Affino instance, it presents the API Key and API Secret from the profile and the AccessToken from the user session. Affino resolves the profile to work out what is allowed, and resolves the AccessToken to work out who is acting. Every write lands with that user's attribution.

That layering is the whole design. Profiles scope capability. Users carry identity. The Bearer token joins the two at the moment of the call.

Before the operator starts, confirm three things on the Affino instance.

• The instance is on Affino 9.0.11 or later. Earlier versions do not ship the MCP service.
• The person configuring the profile holds the API Configuration security right. Without it the API Profiles screen is read-only.
• The object families you plan to expose are themselves enabled on the instance. Articles, Media Items, and Forums only make sense to expose if your instance uses them.

Before an agent user connects, confirm three things about their Affino account.

• They have a real Affino user record on the instance. Agents inherit their identity. If the user cannot log in manually, the agent cannot write on their behalf.
• Their user record has the permissions they want the agent to have. An agent cannot do more than its user can do. If the user cannot create opportunities, neither can the agent.
• Their user record uses an authentication method compatible with token login. Standard email and password accounts work out of the box. SSO-only users may need an operator-issued credential pair specifically for API use, depending on your SSO configuration.

One thing that often surprises operators: there is no shared service account. If an agent user is not signed in or their session has expired, the agent's next write returns an authentication error. The agent should surface that error and prompt the user to log in again rather than silently retrying.

This step belongs to the operator. It takes about ten minutes and produces the credentials the end user needs.

Create the profile

Open Control > Settings > System > API Profiles and click Add. On the API Profile Edit screen, set the following:

• Type: AI. This is the choice that unlocks the MCP-specific behaviour. The older API Profile types pre-date MCP and do not expose the same feature set.
• Name: a short description of the agent workload, not the person, for example Content Editor Agent or CRM Sales Agent. Multiple workloads can share an instance; each gets its own profile.
• Enabled methods: tick the object families and operations you want the agent to use. Start with the narrowest set you can. You can widen later.

Save the profile. The screen now shows the API Key and API Secret. Treat both as credentials. Do not paste them into chat transcripts or commit them to source control.

Prove the connection

On the same profile group, open API Profile CRM Test Tool. The test tool exchanges a real user login for an AccessToken, combines it with the profile's API Key and Secret, and calls one of the profile's enabled methods. A green result confirms three things at once: the profile is valid, the test user can log in, and the selected method is actually enabled.

Worked example: Content Editor Agent

An editorial team wants an agent that drafts articles and uploads cover images, but never touches CRM. The operator creates one profile:

• Type: AI
• Name: Content Editor Agent
• Enabled methods: Articles (read + write), Media Items (read + write)
• All other families: disabled

The test tool runs a read on Articles as the editor's user account. It returns the expected article list. The profile is ready. The operator shares the API Key and API Secret with the editors who will use it.

The authentication flow matters for two groups: operators who need to understand what the agent is actually doing on their instance, and end users whose agent is asking them to do something unexpected like log in again.

How a request is authenticated

1. The user logs in to Affino. This can be a normal browser login or an API login through the User API. The login response returns an AccessToken, a plain UUID tied to the user's record and a matching expiry.
2. The agent client includes three headers on every call to the MCP service: Authorization: Bearer <AccessToken>, X-API-Key: <profile key>, X-API-Secret: <profile secret>.
3. Affino resolves the profile from the API Key and Secret. That determines what the agent is allowed to do.
4. Affino resolves the AccessToken against the active-session store. That determines who is acting. Every create or update carries this user's attribution in the audit trail.
5. If the AccessToken is missing or expired, the call is rejected with an authentication error. There is no fallback to a shared account.

The User API login endpoint

For operators integrating their own tooling, the login endpoint is:

POST /rest/{dbname}/login Headers: APIKey, Signature (SHA-512), MD5, TimeStamp Body: { "Email": "user@example.com", "Password": "..." }

The response includes AccessToken, Expires, and a refresh token. The AccessToken is what gets passed as the Bearer header to the MCP service. For the details of the signature, MD5 and timestamp headers, see API Profile User Help in the Control Centre.

Session lifetime

AccessTokens expire. When they do, the agent's next call fails with a 401. The correct behaviour on the agent side is to surface that error to the user and ask them to re-authenticate rather than attempt to reuse a stale token. Most MCP clients handle this transparently; good ones show a clear re-login prompt, not a silent failure.

This step belongs to the end user. You have the API Key, the API Secret, and an active Affino login. You want your agent to see your instance.

MCP endpoint

Your MCP endpoint is the MCP path on your Affino instance, for example:

https://{your-instance}.affino.com/mcp

Replace {your-instance} with the hostname you use to log in to Affino. If you are unsure which host to use, ask your operator or check the URL you use in the browser.

Claude Desktop and Claude Cowork

Open Settings > Extensions > Connectors, click Add Custom, and enter:

• URL: your MCP endpoint from above
• Headers: Authorization: Bearer <your AccessToken>, X-API-Key: <your API Key>, X-API-Secret: <your API Secret>

Save and restart Claude Desktop. The new connector should list the tools you have access to based on the profile's enabled methods.

If you prefer JSON config, edit ~/Library/Application Support/Claude/claude_desktop_config.json directly:

{ "mcpServers": { "affino": { "type": "http", "url": "https://{your-instance}.affino.com/mcp", "headers": { "Authorization": "Bearer YOUR_ACCESSTOKEN", "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET" } } } }

Claude Code CLI

claude mcp add --transport http affino https://{your-instance}.affino.com/mcp \ --header "Authorization: Bearer YOUR_ACCESSTOKEN" \ --header "X-API-Key: YOUR_API_KEY" \ --header "X-API-Secret: YOUR_API_SECRET"

Codex and other MCP-compatible clients

Any client that speaks streamable-http MCP can connect. Configure it with the same three headers against the same MCP endpoint. The exact config location differs per client, but the shape is identical.

Verify

Ask the agent a simple read question such as List three accounts from my Affino instance. A list response means the connection is working and your profile exposes at least account reads. An authentication error means the AccessToken, API Key, or API Secret is wrong or your session has expired; log in to Affino again and re-issue the AccessToken.

Affino MCP v1 ships with ten object families. Each family is enabled independently in the API Profile, with separate read and write controls where both make sense.

Family	Read	Write	Notes
Accounts	Yes	Yes	Company and organisation records.
Contacts	Yes	Yes	People records, including account linkage and permission management.
Contact Lists	Yes	Yes	Segmentation and mailing-list membership.
Account Lists	Yes	Yes	Account segmentation.
Opportunities	Yes	Yes	Pipeline records, including contacts, team members, and topics.
Tasks	Yes	Yes	CRM tasks.
Notes	Yes	Yes	Attached to accounts, contacts, opportunities.
Articles	Yes	Yes	Full article lifecycle including steps, categories, comments, and media attachments.
Media Items	Yes	Yes	Media library items and their files.
Forums	Yes	Yes	Threads, posts, moderators.

What is not in v1:

• Sections and Channels are not exposed as writeable entities. Articles reference them by code but do not let an agent create new ones.
• Commerce objects (orders, carts, catalogue items, pro formas) are not yet on the MCP surface. They are known candidates for a future release.

If a family is not on the list, assume it is not accessible through the MCP service. Direct REST API access with appropriate credentials remains available for anything else your operator has enabled.

Operators enable or disable any family at any time. Disabling a family on a live profile causes the matching agent tools to disappear from the client on the next reconnect. Existing records are not affected.

This reference covers the seven CRM families. Each follows the same shape: a short description, a realistic example, the argument set, the attribute set returned, and any notes that matter in practice. The authoritative argument and attribute lists are generated from the Affino code at runtime and surfaced on your instance under API Profile CRM Help. Use this guide for understanding and the live help screen for the definitive field lists on your version.

Accounts

Description. Company or organisation records. Accounts are the anchor for opportunities, contacts, and most CRM reporting.

Example usage. Create a new account for Orbital Labs, industry technology, with one primary contact Jane Doe, and mark them as a prospect.

Argument reference. Expect core fields including name (Required), description, industry code, account type, website, address fields, and parent account reference. The exact set is listed on API Profile CRM Help for your instance.

Attribute reference. Create and update return the full account record including the generated AccountCode. Reads return the same shape plus linked contact and opportunity summaries depending on the tool.

Notes. Creates and updates carry the acting user's identity. If an account exists and you want to link a contact rather than duplicate, use the contact permission and account-link tools rather than creating another account.

Contacts

Description. People records. The most commonly touched entity in any CRM-style agent workflow.

Example usage. Create a contact called Jane Doe at Orbital Labs with email jane@orbital.example and job title VP of Engineering.

Argument reference. Email (Required in most configurations), first and last name, job title, account link, phone numbers, address, topic interests. Consult API Profile CRM Help for the full list and which fields are required on your instance.

Attribute reference. The full contact record is returned, including the generated UserCode and resolved account reference when linked at create time.

Notes. Linking a contact to an account is a separate operation; the link tool accepts an existing UserCode and AccountCode. Permission management (for example, consent to marketing) is also separate.

Opportunities

Description. Pipeline records tracking a deal, campaign, or renewal. Opportunities link to one primary account and may include multiple contacts and team members.

Example usage. Open an opportunity against Orbital Labs for the Q2 upsell conversation, estimated £40,000, primary contact Jane Doe, topic 'platform expansion'.

Argument reference. AccountCode (Required), title, value, stage, close date, owner, and optional primary contact. Secondary contacts, team members, and topics attach through their own sub-resource tools.

Attribute reference. The full opportunity record, including the generated OpportunityCode. Sub-resource tools return the sub-resource shape (contact link, team member, topic).

Notes. Opportunities have the richest relational surface in the CRM. Agents frequently need multiple calls to set one up cleanly: create the opportunity, attach contacts, attach team members, and assign topics.

Tasks

Description. Work items scoped to a user, account, contact, or opportunity. Used for follow-ups and reminders.

Example usage. Add a task on the Orbital Labs opportunity: call Jane Doe next Tuesday to confirm the pricing sheet.

Argument reference. Title, due date, owner, and a scoping reference (account, contact, or opportunity). Status starts at pending.

Attribute reference. The full task record including AppUserTaskCode and the resolved scope.

Notes. Tasks are the lowest-cost way for an agent to leave a trail of intent. If the agent cannot yet act, it can at least create a task against the relevant record for a human to pick up.

Notes

Description. Free-text notes attached to accounts, contacts, or opportunities. Useful for agent-captured context that does not fit into structured fields.

Example usage. Add a note on Jane Doe summarising today's call: they want a pricing comparison against competitor X.

Argument reference. Body (Required), subject, and a scope reference (account, contact, or opportunity).

Attribute reference. Returns the full note record including NoteCode.

Notes. Keep notes short and specific. Dumping long chat logs into a note makes the record hard to read later. Summarise, then link back to the full source if needed.

Contact Lists and Account Lists

Description. Segmentation. Both work the same way: a list exists, and members are attached by code.

Example usage. Add Jane Doe to the Spring 2026 Campaign contact list.

Argument reference. List creation takes a title and description. Membership takes a list code and the contact or account code to add or remove.

Attribute reference. List operations return the full list record. Membership operations return confirmation plus the resolved member reference.

Notes. Lists are the cleanest place for an agent to bulk-tag records without mutating the records themselves. Use them for campaign cohorts, audience builds, and segment handovers.

Articles

Description. Affino's canonical content object. Articles are step-based. The article record carries the title, teaser, section, and overall body; each step carries its own heading and body, and may have media attached. Most non-trivial article work on the MCP surface is really step work.

Example usage. Create a draft article titled 'Spring Product Walkthrough' in the Marketing section, teaser 'Everything new in April', then add four steps covering overview, setup, advanced use, and troubleshooting.

Argument reference. Article create takes title (Required), standardSectionCode (Required — where the article lives), teaser, body, article type code, security code, and a live flag. Step create takes article code, title (Required), body text, and sort order.

Attribute reference. Create and update return the full article record including the generated StandardItemCode. Step operations return the step record including its StandardStepByStepCode.

Notes. Three things catch out agents on first use:

• Articles must belong to a section. Look up valid StandardSectionCode values with the article lookups tool before creating.
• Step order matters. If you want steps in a specific order, set sort_order explicitly rather than relying on creation order.
• Publishing is a separate action from creating. A freshly created article is usually not live until the publish tool is called or the live flag is set.

Media Items

Description. Records in the Affino media library. Each media item can have one or more files attached (images, documents, video thumbnails) and is the object referenced when images are attached to article steps.

Example usage. Upload a cover image for the Spring Product Walkthrough article: create a media item titled 'Spring walkthrough cover', attach the image file, then attach the media item to step one of the article.

Argument reference. Media item create takes a title (Required), description, and category. File attachment takes a media item code and a file payload.

Attribute reference. Returns the full media item record including MediaFileItemCode and attached file metadata.

Notes. Agents often forget that the media item and its file are two resources. The item is the record; the file is what actually gets rendered. Attaching a file is a separate call from creating the item.

Forums

Description. Affino's discussion surface. Agents can create threads, reply with posts, moderate, and manage forum moderators. Forum threads are linked to a ForumItemCode, which scopes them to one forum on your instance.

Example usage. Post a reply in the customer-support forum thread about v9.0.11 login issues, summarising the workaround and linking to the help guide.

Argument reference. Thread create takes ForumItemCode (Required), title (Required), and the opening post body. Post create takes ForumThreadCode and body. Moderator operations take a forum and a user reference.

Attribute reference. Returns the full thread or post record with its generated code.

Notes. Threads carry moderation metadata; if the acting user is not a moderator on the target forum, moderation tools return a permission error. That is correct behaviour, not a bug. Agents should not be able to moderate forums their user is not authorised to moderate.

A working connection is the first half of a good integration. Operational visibility is the other half.

API Logs

Every call through the MCP service is recorded in the Affino API Logs. The log row captures the API Profile that made the call, the user whose identity was used, the method called, the arguments, the status code, and any Affino-side warnings or errors.

For operators, this is the primary debugging surface. When an agent user reports that the agent is not working, the API Log row is where the truth lives. Warnings typically mean the call succeeded but the arguments were partially ignored; errors mean the call was rejected.

For agent users, the log is the audit trail. Every create, update, or delete made by the agent is recorded against your user name and visible to your operator on the same footing as any manual change.

Rate limiting

The MCP service is rate-limited on a per-profile basis. When the limit is hit, calls return HTTP 429 with a short cool-down. Agents should back off when they see 429 rather than retry immediately. If rate-limiting becomes a chronic problem for a workload, the operator can adjust the profile's rate limit upward or split the workload across multiple profiles.

Brute-force protection

Authentication endpoints have stricter protection than the main MCP surface. An agent client that sends repeated invalid tokens to the login endpoint will be temporarily blocked. Valid credentials are never rate-limited; this protection only fires on auth failures.

Disabling a profile

An operator can disable a profile at any time. When disabled, new calls using its API Key and Secret are rejected. Any active MCP connections drop on the next call. There is no partial disable; the profile is either on or off.

Rotating credentials

API Secrets can be regenerated from the profile edit screen. Regenerating invalidates the old secret immediately. Coordinate with the agent users who hold the old secret before doing this in production.

Common issues and how to work through them.

The agent cannot see any tools

The most common first-connection failure. Causes, in order of likelihood:

• API Key or API Secret is wrong. Recheck the values in the agent's config against the API Profile edit screen.
• The AccessToken has expired. Log in to Affino again in the browser; most clients pick up the new session automatically.
• The profile is disabled. Operators, confirm the profile is active on the API Profiles list.

The API Profile CRM Test Tool and API Profile User Test Tool screens in the Control Centre are the fastest way for the operator to check whether the profile-plus-user combination is valid, independent of the agent client.

A specific tool returns permission denied

The agent can see tools but one of them fails. Usually not an MCP issue; usually a user-permission issue. Agents inherit their user's rights, so if the user cannot do X in the Control Centre, the agent cannot either. Check the user's role and security group for the resource the agent is trying to touch.

A create succeeds but the record looks wrong

Check the API Log row for warnings. Common patterns:

• A required field was missing and the system filled in a default you did not want.
• A provided field was ignored because the profile does not expose write to that field.
• A code reference (section, account, forum) did not resolve, and the field fell back to a default.

Warnings are not errors, but they often explain the drift between what the agent asked for and what ended up in the record.

Writes are silently attributed to the wrong user

This should not happen. If it does, check two things:

• The agent client is passing the correct AccessToken in the Bearer header. Some clients cache tokens across accounts.
• The user has only one active session. Having several simultaneous sessions can make the "acting user" ambiguous if the wrong token was picked.

Affino always prefers the Bearer token for identity. If the Bearer is wrong, attribution is wrong.

What to avoid

• Do not share AccessTokens between people. The audit trail assumes one token belongs to one person. A shared token silently misattributes every write.
• Do not hardcode credentials in agent prompts or instructions. Use the agent client's config file or environment variables. Credentials in prompts tend to leak into logs and conversation history.
• Do not enable every method on a profile 'just in case.' Scope the profile to the narrowest set that works for the intended workload. Widening later is one save; narrowing later after misuse is harder.
• Do not treat MCP as a direct replacement for the REST API. The MCP surface is curated for agent workflows. Some operator-grade operations (bulk imports, schema changes, integration-specific endpoints) remain on the REST API and are not exposed through MCP by design.
• Do not skip the test tool. Two minutes on the test tool saves twenty minutes of agent-side debugging when something is off.