setup-mcp
Configure Model Context Protocol (MCP) servers in .agents/mcp_config.json (project-level) or ~/.gemini/config/mcp_config.json (global). User-invoked skill.
- License 许可
- MIT
- 最近更新
- 2026-08-29
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- setup-mcp
- description
- Configure Model Context Protocol (MCP) servers in .agents/mcp_config.json (project-level) or ~/.gemini/config/mcp_config.json (global). User-invoked skill.
03 SKILL.md 正文
Setup MCP
Configure Model Context Protocol (MCP) servers for Antigravity, connecting the agent to external tools, databases, APIs, and local services.
This is a user-invoked skill (/setup-mcp). It walks developers through selecting transport types, configuring server definitions, injecting environment variables safely, and verifying server connectivity.
Target Configuration Files
Antigravity discovers MCP servers from two primary configuration files:
-
Project-level:
.agents/mcp_config.json(or.agent/mcp_config.json)- Located at the repository root.
- Ideal for project-specific tools: local development databases, repository-scoped filesystem servers, repo git tools, and project mock servers.
- Can be committed to version control to share tool configurations across the team (without committing secrets).
-
Global:
~/.gemini/config/mcp_config.json- Located in the user's home directory.
- Ideal for personal credentials, global developer utilities, cross-project integrations, and machine-wide services.
Both files use the standard mcpServers object format:
{
"mcpServers": {
"<server-name>": {
...
}
}
}
Supported Transports & Schemas
1. Stdio Transport (Local Process)
Used for local command-line tools, scripts, or package runners (npx, uvx, node, python). The language server spawns the child process and communicates via standard input and standard output.
JSON Schema:
{
"command": "executable-name-or-path",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR_NAME": "value"
},
"cwd": "/optional/working/directory"
}
command(string, required): Executable name onPATH(for examplenpx,uvx,node,python) or an absolute path to a binary.args(array of strings, optional): Command-line arguments passed to the executable.env(object, optional): Environment variables injected into the child process.cwd(string, optional): Working directory for process execution.
2. SSE Transport (Server-Sent Events)
Used for remote MCP services accessible over HTTP via Server-Sent Events.
JSON Schema:
{
"serverUrl": "https://mcp.example.com/sse",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
serverUrl(string, required): Full HTTP(S) URL of the remote SSE endpoint.headers(object, optional): Custom HTTP headers for authentication and routing.
3. HTTP Transport (Streamable HTTP Endpoint)
Used for remote MCP servers using streamable HTTP or REST endpoints.
JSON Schema:
{
"url": "https://mcp.example.com/api",
"headers": {
"Authorization": "Bearer YOUR_TOKEN",
"X-Custom-Header": "value"
}
}
url(string, required): Full HTTP(S) URL of the MCP endpoint.headers(object, optional): Custom HTTP headers such as bearer tokens or API keys.
Common Server Recipes
PostgreSQL Server (@modelcontextprotocol/server-postgres)
Exposes PostgreSQL database inspection and query tools.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://user:password@localhost:5432/mydb"
]
}
}
}
Or using an environment variable for credentials:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_URL": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}
Filesystem Server (@modelcontextprotocol/server-filesystem)
Grants scoped file read, write, and directory inspection capabilities. Always provide explicit allowed directory paths as arguments.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory",
"/second/allowed/directory"
]
}
}
}
GitHub Server (@modelcontextprotocol/server-github)
Enables searching repositories, reading issues, managing pull requests, and inspecting file contents across GitHub.
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourPersonalAccessToken"
}
}
}
}
Git Server (@modelcontextprotocol/server-git)
Enables reading commit history, diffs, branches, and status from a local git repository.
Node / npx version:
{
"mcpServers": {
"git": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-git",
"--repository",
"/path/to/local/git/repo"
]
}
}
}
Python / uvx version:
{
"mcpServers": {
"git": {
"command": "uvx",
"args": [
"mcp-server-git",
"--repository",
"/path/to/local/git/repo"
]
}
}
}
Custom Local Node.js Server
Used for proprietary or internal MCP servers written in TypeScript or JavaScript.
{
"mcpServers": {
"my-node-tools": {
"command": "node",
"args": ["./scripts/mcp-server.js"],
"cwd": "/path/to/project",
"env": {
"NODE_ENV": "development",
"API_KEY": "secret-key"
}
}
}
}
Custom Local Python Server
Used for custom Python MCP servers built with the FastMCP or MCP Python SDK.
{
"mcpServers": {
"my-python-tools": {
"command": "python",
"args": ["-m", "my_mcp_package.server"],
"env": {
"PYTHONPATH": "./src",
"SERVICE_ENDPOINT": "http://localhost:8080"
}
}
}
}
Or using uv run:
{
"mcpServers": {
"my-python-tools": {
"command": "uv",
"args": ["run", "--with", "mcp", "python", "./scripts/server.py"]
}
}
}
Workflow and Execution Steps
When /setup-mcp is invoked, follow this structured process:
1. Scope and Needs Assessment
Ask the developer what service, database, or tool they want to connect:
- Identify if this is a standard recipe (PostgreSQL, Filesystem, GitHub, Git) or a custom server.
- Determine configuration scope:
- Project-level (
.agents/mcp_config.json): Default for repo-specific tools. - Global (
~/.gemini/config/mcp_config.json): For personal tools and machine-wide access.
- Project-level (
- Check if the target config file already exists and parse its existing
mcpServers. - Upstream verification: If configuring an unfamiliar or external MCP package, use
search_webandread_url_contentto fetch the authoritative npm/PyPI documentation, required environment variables, and CLI argument schema from primary sources before drafting the JSON.
2. Configure Server Entry
Draft the server configuration object according to the selected transport:
- Verify executable paths and command availability (
npx,uvx,node,python). - Map all necessary arguments and environment variables.
- Keep secrets safe: remind the developer to use local environment variables or private global configs if the project config is committed to public source control.
3. Write and Merge
- Read the target configuration file if it exists.
- Preserve all existing server definitions under
mcpServers. - Add or update the target server definition under its designated key name.
- Format the JSON file cleanly with 2-space indentation.
- Ensure the parent directory (
.agents/or~/.gemini/config/) exists before writing.
4. Verification Step
Run proactive diagnostics to ensure the configured MCP server will start cleanly:
- Syntax and JSON check: Ensure the output file is valid JSON with top-level
mcpServersmapping. - Command / Binary check: Test if the command exists and is executable in the current environment (for example running
npx --version,python --version, or verifying local script file paths). - Environment variable check: Verify all required keys in the
envblock are populated with non-empty values. - Path & Permission check:
- For filesystem servers: verify target paths exist and have appropriate read/write permissions.
- For database servers: verify database port and host are reachable.
- For git servers: verify the directory is a valid git repository.
- For remote SSE/HTTP servers: verify the URL endpoint is reachable.
5. Final Confirmation
Report the setup outcome to the user:
- Show the exact JSON configuration block that was written.
- Specify the configuration path (
.agents/mcp_config.jsonor~/.gemini/config/mcp_config.json). - Mention how Antigravity will discover the new tools on next prompt or agent reload.
04 同仓库更多 Skills
writing-shape
Shape raw material into an article paragraph by paragraph, arguing format choices along the way.
writing-fragments
Mine raw writing fragments with no structure yet, capturing ideas into a single quarry file.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
writing-beats
Assemble raw material into a narrative journey of beats, grounding concepts before leaning on them.
wait-what
Stop. That last message did not land: re-pitch it.
to-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.