MCP tool reference

Every tool the Diffinery MCP server offers, generated from the server's own tool list, so it always matches what tools/list returns. For setup in Claude Code, Cursor and other clients, read MCP.

#Connection

• Endpoint: https://diffinery.com/mcp (Streamable HTTP; responses are JSON, not event streams).
• Authentication: Authorization: Bearer dfy_..., a token for an agent or a person. Every call needs an active account.
• Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05. The server answers with the version the client asks for when it supports it, else the newest.
• Every tool runs through the same permission checks, branch protection and agent guardrails as git and the REST API.
• Errors come back as a tool result with isError: true and the message as text. Successful results carry the JSON both as text and as structuredContent.

#Tools

#Identity and repositories

#whoami

Show the account this token acts as, including the human an agent works on behalf of.

Read-only: yes.

No arguments.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}

#list_repos

List repositories visible to you, optionally filtered by owner.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_repos","arguments":{}}}

#Code

#list_tree

List files and directories at a path in a repository.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_tree","arguments":{"owner":"acme","repo":"website"}}}

#get_file

Read a file's contents.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_file","arguments":{"owner":"acme","repo":"website","path":"README.md"}}}

#commit_files

Create one commit that writes and deletes files on a branch, without a git client. Pass expected_head_sha to avoid racing other writers; pass create_branch_from to start a new branch.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commit_files","arguments":{"owner":"acme","repo":"website","branch":"main","message":"..."}}}

#Branches and commits

#list_branches

List branches, marking the default and protected ones.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_branches","arguments":{"owner":"acme","repo":"website"}}}

#create_branch

Create a branch from another branch, tag or commit.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_branch","arguments":{"owner":"acme","repo":"website","branch":"main"}}}

#compare

Compare two refs: commits ahead/behind and a unified diff.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compare","arguments":{"owner":"acme","repo":"website","base":"...","head":"..."}}}

#Pull requests

#list_pull_requests

List pull requests.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_pull_requests","arguments":{"owner":"acme","repo":"website"}}}

#get_pull_request

Get a pull request with its conversation, reviews, mergeability and (optionally) the full diff. mergeability.blockers is what stops you merging it yourself now. For agents and workflow tokens, auto_merge_blockers is what stops Diffinery landing it through auto-merge or the merge queue (enable_auto_merge): an empty list means it would land now.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#create_pull_request

Open a pull request. Use intent to explain the goal for reviewers (agents should always set it). auto_merge: true turns on auto-merge as it opens (it merges once required checks pass and every rule of the base branch is met), false keeps it off where your own setting would turn it on; autoMergeSkipped says why it stayed off when you asked.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_pull_request","arguments":{"owner":"acme","repo":"website","title":"...","head":"..."}}}

#review_pull_request

Submit a review: APPROVE, REQUEST_CHANGES or COMMENT, with optional line comments [{ path, line, side?, body }]. Agent approvals never count toward required human approvals of agent-authored PRs.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"review_pull_request","arguments":{"owner":"acme","repo":"website","number":"42","event":"..."}}}

#merge_pull_request

Merge a pull request when it is mergeable (checks, approvals and branch protection are enforced). When the base branch uses a merge queue, this adds the pull request to the queue instead; it merges once its merge group passes the required checks. Agents can't merge into protected or default branches themselves: use enable_auto_merge there.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"merge_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#enable_auto_merge

Turn on auto-merge: Diffinery merges the pull request by itself as soon as every branch rule is met (required checks green on the head, approvals from people, linear history), or adds it to the merge queue when the base branch uses one. This is how an agent lands a change on a protected or default branch: it is allowed only where the branch protection sets allowAgentAutoMerge and has at least one required check, and nothing is bypassed. A push to the branch by anyone else turns it off.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"enable_auto_merge","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#disable_auto_merge

Turn off auto-merge on a pull request.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"disable_auto_merge","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#dequeue_pull_request

Remove a pull request from its base branch's merge queue.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dequeue_pull_request","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#Issues

#comment

Comment on an issue or pull request.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"comment","arguments":{"owner":"acme","repo":"website","number":"42","body":"..."}}}

#list_issues

List or search issues.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_issues","arguments":{"owner":"acme","repo":"website"}}}

#get_issue

Get an issue with its comments.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_issue","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#create_issue

Open an issue.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_issue","arguments":{"owner":"acme","repo":"website","title":"..."}}}

#update_issue

Update an issue or pull request: title, body, state (open/closed), labels.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_issue","arguments":{"owner":"acme","repo":"website","number":"42"}}}

#Actions

#list_workflow_runs

List workflow runs, newest first. Filter by branch, commit sha, PR number or status.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workflow_runs","arguments":{"owner":"acme","repo":"website"}}}

#get_workflow_run

Get a run with its jobs, their status, conclusion and failure reason.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_workflow_run","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}

#get_job_logs

Fetch a job's log as plain text. Use tail to limit to the last N lines (default 400).

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_job_logs","arguments":{"owner":"acme","repo":"website","job_id":"..."}}}

#rerun_workflow

Re-run a finished workflow run as a new attempt. With failed_only, only the jobs that failed, were cancelled or timed out run again (with the jobs that depend on them); the others keep their results.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rerun_workflow","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}

#rerun_job

Re-run one job (one matrix leg) of a finished run, with the jobs that depend on it, as a new attempt of the run; the other jobs keep their results.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rerun_job","arguments":{"owner":"acme","repo":"website","job_id":"..."}}}

#cancel_workflow

Cancel a queued or running workflow run.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"cancel_workflow","arguments":{"owner":"acme","repo":"website","run_id":"..."}}}

#dispatch_workflow

Start a workflow_dispatch run, e.g. workflow 'deploy.yml' on ref 'main' with inputs.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"dispatch_workflow","arguments":{"owner":"acme","repo":"website","workflow":"ci.yml"}}}

#Releases

#list_releases

List a repository's releases, newest first. Drafts are included only for writers.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_releases","arguments":{"owner":"acme","repo":"website"}}}

#get_release

Get a release by tag, by id, or the latest release when neither is given.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_release","arguments":{"owner":"acme","repo":"website"}}}

#create_release

Create a release. Creates the tag at target_commitish (default branch by default) when it doesn't exist yet.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_release","arguments":{"owner":"acme","repo":"website","tag_name":"..."}}}

#update_release

Edit a release: title, notes, tag, draft or prerelease state. Publishing a draft sends the release event.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_release","arguments":{"owner":"acme","repo":"website","id":"..."}}}

#upload_release_asset

Attach a file (up to 25 MB) to a release. Pass text as content, or bytes as content_base64.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"upload_release_asset","arguments":{"owner":"acme","repo":"website","release_id":"...","name":"website"}}}

#generate_release_notes

Draft release notes for a tag from the pull requests merged since the previous release. Doesn't create anything.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_release_notes","arguments":{"owner":"acme","repo":"website","tag_name":"..."}}}

#Imports

#start_github_import

Start a server-side import of a GitHub repository into Diffinery: git history (keeping issue and pull-request numbers), issues and pull requests with comments and reviews, labels, milestones, branch protection, Actions variables, releases and deployment environments. Secret VALUES are never read from GitHub (only their names are reported, to set by hand), and push protection is never bypassed on an agent's behalf. An agent can import only where its owner may: the owner's own account or an organization the owner administers (an organization's agent: that organization), and only when the agent's policy allows write. Returns the import id; poll it with get_import.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"start_github_import","arguments":{"source":"...","owner":"acme"}}}

#get_import

Get an import you started: its status, per-step progress, warnings, any error, and (for an organization import) its repositories.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_import","arguments":{"id":"..."}}}

#list_imports

List the imports you have started, newest first.

Read-only: yes.

No arguments.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_imports","arguments":{}}}

#Sandboxes

#sandbox_create

Start an isolated Linux sandbox with the repository checked out (git push from inside it uses your permissions). Returns a sandbox id.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_create","arguments":{"owner":"acme","repo":"website"}}}

#sandbox_exec

Run a shell command in a sandbox. Returns exit code, stdout and stderr.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_exec","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","command":"..."}}}

#sandbox_read_file

Read a file inside a sandbox.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_read_file","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","path":"README.md"}}}

#sandbox_write_file

Write a file inside a sandbox.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_write_file","arguments":{"owner":"acme","repo":"website","sandbox_id":"...","path":"README.md","content":"..."}}}

#sandbox_close

Shut down a sandbox.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sandbox_close","arguments":{"owner":"acme","repo":"website","sandbox_id":"..."}}}

#Docs

#search_docs

Search the Diffinery documentation (workflows, API, git, agents, settings) and the site's product, comparison and FAQ pages. Returns the best matching pages and sections with a snippet; read one with read_docs.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"..."}}}

#read_docs

Read a Diffinery documentation page as Markdown. Pass its slug (like 'actions/workflow-syntax'), or 'index' for the overview, which links to every page. Site pages work too, by path (like '/compare/github' or '/faq').

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_docs","arguments":{"page":"..."}}}

#Other

#get_organization

Show an organization: its name and, to its members and their agents, the base permission every member gets on its repositories (default_repository_permission: none, read, write or admin).

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_organization","arguments":{"org":"acme"}}}

#list_invitations

List pending invitations to a repository (owner and repo, for its admins), an organization (org, for its owners and admins), or the site (neither, for site admins).

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_invitations","arguments":{}}}

#revoke_invitation

Revoke a pending invitation by id (from list_invitations), so it can't be accepted and the address can be invited again. Takes the same owner and repo, org, or neither as list_invitations.

Read-only: no.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"revoke_invitation","arguments":{"invitation_id":"..."}}}

#today

Your morning view across every repository you can see: pull requests that need you (review requests, agent pull requests waiting for a person's approval, your own blocked ones), what your agents are working on and where each stands, and what merged, was released or failed in the last 24 hours.

Read-only: yes.

No arguments.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"today","arguments":{}}}

#agent_tasks

List agent tasks. With owner and repo: that repository's tasks (you need write access). Without: the tasks you started (for an agent: the tasks it runs). Starting, steering and retrying tasks happens on the web, by the person whose model key it spends.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_tasks","arguments":{}}}

#project

A repository as a project: its task board grouped by state (waiting on you, working, queued, ready for review, landing, done, idle), the project's memory and its settings (how many tasks run at once, instructions every task gets). You need write access.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project","arguments":{"owner":"acme","repo":"website"}}}

#project_posts

The project conversation: people's posts and task events, oldest first, after after (a post id), or the latest 100. Posting happens on the web, by a person.

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project_posts","arguments":{"owner":"acme","repo":"website"}}}

#agent_task

One agent task: its goal, state, runs, branch and pull request, and its transcript after after (a line number; default from the start, at most 500 lines).

Read-only: yes.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_task","arguments":{"owner":"acme","repo":"website","number":"42"}}}