MCP Server guidelines
These best practices are for partners who build MCP (Model Context Protocol) servers on top of the current Netvisor APIs. They complement the existing Netvisor integration instructions:
Access and security
Use an additional authorisation layer
If external third-party integrators or agent service providers will use your MCP server, we strongly recommend an additional authorisation layer. In this setup, Visma is the first party and you are the second party. The additional layer prevents accidental or unauthorised changes to business data.
Respect company and environment boundaries
Every MCP tool call must run in the correct company context. Your MCP server must not allow:
data access across companies
mixing of credentials
implicit expansion of privileges
Use only official APIs
Your MCP server should only use supported Netvisor APIs. It must not bypass the official APIs through database access, internal UI paths, hidden endpoints or backend classes.
Write actions
Make the server read-only by default
Your MCP server should mainly offer read, search and metadata lookup capabilities. On the current API surface, treat write actions as higher risk, because automated tool use can create inconsistent or unintended data.
Until validation, permissions and API contracts are stronger, enable write actions only for narrowly scoped use cases and with explicit safeguards.
Require human review for write actions
If your MCP server can create, update or delete business data, we recommend a human review step before the action runs. This is especially important for financial data, for example:
sales invoices
customer details
payment terms
dimensions
status transitions
The MCP server must clearly show the side effects of the action before approval.
Validate data before you call the Netvisor API
Before your MCP server sends a request to Netvisor, it must validate:
all required fields
enum values
identifiers
the company context
business preconditions
Invalid requests should fail fast with clear, machine-readable error messages. Do not rely on later steps to correct them. This reduces unnecessary processing and repeated retries.
Use idempotent write actions
Use idempotent write actions whenever possible. Your MCP server must protect against duplicate writes caused by retries, model loops or repeated submissions by users. This is critical especially for invoice creation and other financial transactions. Running a tool again must not silently create several identical objects.
API usage
Stay within rate limits
Rate limiting is mandatory. Design your MCP server to work within current and future Netvisor API rate limits. This includes any limits that may be introduced for specific endpoints, partners or companies.
Minimise polling
Avoid continuous polling. If you cannot avoid polling, use caching, backoff and sensible intervals. Your MCP integration must not query the same resources again and again at high frequency only to detect changes.
Netvisor APIs are expected to develop stronger data contracts and better support for change notifications.
Logging and tool descriptions
Log every call
Log each MCP call. The log must contain:
tool name
company context
caller identity
correlation ID
called API
result
latency
For write actions, the approval chain must also be traceable.
Write clear tool descriptions
Each MCP tool description must clearly state:
the purpose of the tool
required inputs
side effects
company scope
situations where the tool must not be used
Clear descriptions reduce errors made by AI agents and improve the quality of the implementation.
Where possible, add documentation that is suitable for language models. It should explain domain concepts, the purpose of workflows, constraints and recommended usage patterns. For an example, see Stripe's documentation on building with AI.