Full Capabilities Reference

Version: 0.7.5 | API Version: Dataverse Web API v9.2 | Transport: stdio · HTTP/SSE

79 tools · 4 resources · 5 prompts across 27 categories for full Dataverse lifecycle management.

For detailed input/output examples, see the Use Cases section.

---

Tool Summary

#	Category	Count	Tools
1	Auth	1	whoami
2	Metadata	9	list_tables, get_table_metadata, get_relationships, list_global_option_sets, get_option_set, get_entity_key, get_attribute_option_set, update_entity, resolve_entity_name
3	Query	3	query, execute_fetchxml, retrieve_multiple_with_paging
4	CRUD	6	get, create, update, delete, upsert, assign
5	Relations	4	associate, associate_bulk, disassociate, query_associations
6	Actions & Functions	6	execute_action, execute_function, execute_bound_action, execute_bound_function, list_dependencies, retrieve_dependencies_for_delete
7	Batch	1	batch_execute
8	Change Tracking	1	change_detection
9	Solutions	2	publish_customizations, create_sitemap
10	Impersonation	1	impersonate
11	Customization	4	list_custom_actions, list_plugin_steps, set_workflow_state, list_connection_references
12	Environment	4	get_environment_variable, set_environment_variable, create_environment_variable, environment_capabilities
13	Trace	2	get_plugin_trace_logs, get_workflow_trace_logs
14	Search	1	search
15	Audit	1	get_audit_log
16	Quality	1	detect_duplicates
17	Annotations	2	get_annotations, create_annotation
18	Users	2	list_users, get_user_roles
19	RBAC	7	list_roles, assign_role_to_user, remove_role_from_user, assign_role_to_team, get_role_privileges, add_role_privileges, replace_role_privileges
20	Views	1	list_views
21	Files	2	upload_file_column, download_file_column
22	Org	2	list_business_units, list_teams
23	Workflows	4	list_workflows, get_workflow, list_guides, get_guide
24	Assistance	2	suggest_tools, list_tool_tags
25	Attributes	4	create_attribute, update_attribute, delete_attribute, create_lookup_attribute
26	Schema (write)	2	create_table, create_relationship
27	Record Access	4	check_record_access, grant_access, revoke_access, merge_records
	Total	79

All tool names are prefixed with dataverse_ (e.g., dataverse_query, dataverse_create).

---

Architecture Overview

MCP Dataverse Server (79 tools · 4 resources · 5 prompts · 27 categories)
├── 🔑 Auth (1)
├── 📋 Metadata (9)
├── 🔍 Query (3)
├── ✏️ CRUD (6)
├── 🔗 Relations (4)
├── ⚡ Actions & Functions (6)
├── 📦 Batch (1)
├── 🔄 Change Tracking (1)
├── 🧩 Solutions (2)
├── 👤 Impersonation (1)
├── 🔧 Customization (4)
├── ⚙️ Environment (4)
├── 🔎 Trace (2)
├── 🔍 Search (1)
├── 📜 Audit (1)
├── ✅ Quality (1)
├── 📝 Annotations (2)
├── 👥 Users (2)
├── 🛡️ RBAC (7)
├── 👁️ Views (1)
├── 📁 Files (2)
├── 🏢 Org (2)
├── ⚙️ Workflows (4)
├── 🤖 Assistance (2)
├── 🏗️ Attributes (4)
├── 📐 Schema (2)
├── 🔐 Record Access (4)
├── 📂 Resources (4)   ← MCP Resources (static + templates)
└── 💬 Prompts (5)    ← MCP Prompts

All tool handlers validate inputs with Zod before calling the Dataverse Web API. Auth tokens are cached and refreshed proactively; transient errors (429, 503, 504) are retried with exponential backoff.

---

MCP Resources

Four read-only MCP resources provide direct contextual data to AI clients that support the MCP Resources spec (Claude Desktop, Cursor). Each returns JSON or plain text without requiring a tool call.

URI	Type	MIME Type	Description
dataverse://tables	Static	application/json	Lists all tables in the environment (LogicalName, DisplayName, EntitySetName)
dataverse://server/instructions	Static	text/plain	Agent best practices and tool usage guidelines
dataverse://tables/{tableName}/schema	Template	application/json	All columns, types, requirement levels, and constraints for a table
dataverse://tables/{tableName}/relationships	Template	application/json	All 1:N, N:1, and N:N relationships for a table

Client support: Resources are fully supported in Claude Desktop and Cursor. GitHub Copilot VS Code and Codex CLI support MCP Tools only; use dataverse_list_tables + dataverse_get_table_metadata as substitutes.

---

MCP Prompts

Five built-in prompt templates guide AI agents through complex multi-step Dataverse workflows. Each prompt composes tools in a recommended sequence and returns a structured report.

Prompt name	Required args	Optional args	Purpose
analyze-org-health	(none)	(none)	Full org health: table count, roles, workflows summary
data-quality-check	tableName	sampleSize (default: 50, max: 500)	Nullity rates, duplicate detection, completeness score
schema-review	tableName	(none)	Schema best practices for naming, types, relations, views
security-audit	(none)	(none)	Over-privileged users, empty teams, orphaned role assignments
analyze-workflow	(none)	workflowName (substring filter), statusFilter (active/inactive/all, default: active)	Workflow health, error rates, ownership

---

Key Features

Structured Outputs

Every tool returns a consistent structure:

{
  "summary": "Human-readable summary of the result",
  "data": {},
  "suggestions": ["Next steps the AI agent can take"]
}

When an error has a well-known root cause, tools also include an errorCategory field to enable programmatic error handling:

Value	Meaning
ENV_LIMITATION	Feature not enabled or unavailable in this environment
PERMISSIONS	Insufficient privileges for the operation
SCHEMA_MISMATCH	Input conflicts with the table’s metadata schema

Guardrails

• Destructive operations (delete, update_entity) require confirm: true
• Query guardrails warn about missing $select, missing $filter, and large result sets
• RBAC operations are idempotent — assigning an already-assigned role returns "already_assigned" instead of an error

ETag Support

dataverse_update accepts an optional etag parameter for optimistic concurrency control. When provided, the update only succeeds if the record hasn't been modified since the ETag was obtained.

Impersonation

Any tool can be executed on behalf of another user via dataverse_impersonate, using the MSCRMCallerId header. Requires prvActOnBehalfOfAnotherUser privilege.

---

Error Handling & Retry

Status	Behavior	Attempts
401	Invalidate token, retry with fresh token	1
429 / 503 / 504	Exponential backoff (2^attempt × 1000 ms)	maxRetries (default 3)
Other	Throw immediately with actionable message	0

---

Security

Feature	Details
Token encryption	AES-256-GCM cached credentials at ~/.mcp-dataverse/
OData injection	esc() utility for single-quote escaping
File column safety	columnName validated against /^[a-zA-Z0-9_]+$/
Impersonation cleanup	MSCRMCallerId cleaned in finally block
No secrets in logs	PAT, tokens, and headers never appear in tool responses

---

Limitations

Area	Limitation
Transport	stdio (default) and HTTP. Server must be spawned or run as HTTP service.
Single environment	One Dataverse environment per server instance
No streaming	Responses are complete JSON; large result sets may exceed AI context limits
$top max	dataverse_query caps at 5 000 per call; use retrieve_multiple_with_paging for more
Paging max	retrieve_multiple_with_paging caps at 50 000 records
Batch max	1 000 operations per $batch request
No $<Content-ID>	Cross-referencing created entities within a changeset not supported
Token expiry	Refresh tokens expire after ~90 days of inactivity

For the complete technical reference with parameter tables, see CAPABILITIES.md on GitHub.