Agent MCP Server - SMKRV MCP Studio

The Agent MCP Server is a standalone MCP endpoint that lets AI agents programmatically manage SMKRV MCP Studio configuration. Agents can create connections, build tools, deploy servers, and more — all through the standard MCP protocol.

Quick Start

1. Start Services

docker compose up -d

2. Set Service Token

Add STUDIO_AGENT_SERVICE_TOKEN to your .env file:

STUDIO_AGENT_SERVICE_TOKEN=your-strong-random-secret

3. Create an Agent Token

Open the Studio UI, navigate to Agent Access, click Create Token, enter a name and duration, then copy the generated token.

4. Connect Your MCP Client

{
  "mcpServers": {
    "smkrv-studio": {
      "url": "http://localhost:3000/agent-mcp/",
      "headers": {
        "Authorization": "Bearer smkr_..."
      }
    }
  }
}

Authentication Methods

Temporary Tokens

Best for interactive sessions, testing, and short-lived tasks.

Property	Value
Duration	15 minutes to 3 hours
Format	`smkr_<40-char-random>`
Revocation	Instant via UI or API

Include the token as a Bearer header:

Authorization: Bearer smkr_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcd

OAuth2 Client Credentials

Best for automated pipelines, CI/CD, and long-running integrations.

Property	Value
Idle Timeout	15 minutes to 24 hours (sliding window)
Grant Types	`client_credentials`, `refresh_token`

Step 1 — Create client (one-time): Create via the UI (Agent Access > OAuth2 Clients) or API. Save the client_id and client_secret — the secret is shown only once. Step 2 — Exchange credentials for tokens:

curl -X POST http://localhost:3000/agent-mcp/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=smkr_cl_...&client_secret=smkr_cs_..."

Step 3 — Use access token:

{
  "mcpServers": {
    "smkrv-studio": {
      "url": "http://localhost:3000/agent-mcp/",
      "headers": {
        "Authorization": "Bearer smkr_at_..."
      }
    }
  }
}

Step 4 — Refresh when expired:

curl -X POST http://localhost:3000/agent-mcp/oauth/token \
  -d "grant_type=refresh_token&refresh_token=smkr_rt_..."

Comparison

Feature	Temporary Token	OAuth2
Setup	Single step	Create client + exchange
Max lifetime	3 hours	24 hours (idle)
Auto-renewal	No	Yes (refresh token)
Best for	Testing, interactive	CI/CD, automation

MCP Client Configuration

Claude Code

{
  "mcpServers": {
    "smkrv-studio": {
      "url": "http://localhost:3000/agent-mcp/",
      "headers": {
        "Authorization": "Bearer smkr_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "smkrv-studio": {
      "url": "http://localhost:3000/agent-mcp/",
      "headers": {
        "Authorization": "Bearer smkr_..."
      }
    }
  }
}

Production (with SSL)

{
  "mcpServers": {
    "smkrv-studio": {
      "url": "https://agent.studio.example.com/",
      "headers": {
        "Authorization": "Bearer smkr_..."
      }
    }
  }
}

Tool Reference

All 37 tools return structured JSON. Pagination uses skip/limit parameters.

Connections (8 tools)

Tool	Description
`list_connections`	List all database connections
`get_connection`	Get connection details
`create_connection`	Create a new connection
`update_connection`	Update connection fields
`delete_connection`	Delete a connection
`test_connection`	Test database connectivity
`list_tables`	List tables in database schema
`list_columns`	List columns of a table

Tools (7 tools)

Tool	Description
`list_tools`	List MCP tools
`get_tool`	Get tool with parameters
`create_tool`	Create a tool
`update_tool`	Update a tool
`delete_tool`	Delete a tool
`duplicate_tool`	Create a copy
`preview_sql`	Execute read-only SQL

Resources (5 tools)

Tool	Description
`list_resources`	List MCP resources
`get_resource`	Get resource details
`create_resource`	Create a resource
`update_resource`	Update a resource
`delete_resource`	Delete a resource

Prompts (5 tools)

Tool	Description
`list_prompts`	List MCP prompts
`get_prompt`	Get prompt with template
`create_prompt`	Create a prompt
`update_prompt`	Update a prompt
`delete_prompt`	Delete a prompt

Deploy (3 tools)

Tool	Description
`deploy_server`	Generate code and start MCP server
`stop_server`	Stop the running server
`get_deploy_status`	Check server status

Export/Import (2 tools)

Tool	Description
`export_config`	Export full configuration as JSON
`import_config`	Import configuration

History (3 tools)

Tool	Description
`list_history`	List audit trail entries
`get_entity_history`	History for a specific entity
`rollback`	Rollback to a previous snapshot

Monitoring (3 tools)

Tool	Description
`get_metrics_stats`	Per-tool aggregate metrics
`get_metrics_timeseries`	Time-series data
`get_queue_metrics`	Redis queue status

Flow (1 tool)

Tool	Description
`get_flow_layout`	Complete configuration snapshot

Rate Limiting

Each token is rate-limited to a configurable number of requests per minute (default: 120). Configure via STUDIO_AGENT_RATE_LIMIT env variable or Studio settings.

Activity Log

All agent tool calls are recorded in Redis with timestamp, token prefix, tool name, client IP, and success status. View in the UI on the Agent Access page or via GET /api/v1/agent-activity.

Security Best Practices

Use short-lived tokens for testing (15-30 minutes)
Rotate OAuth2 client secrets periodically
Set a strong service token (STUDIO_AGENT_SERVICE_TOKEN)
Monitor the activity log for unexpected patterns
Use dedicated domains in production for better isolation
Revoke tokens immediately when compromised

Environment Variables

Variable	Default	Description
`STUDIO_AGENT_SERVICE_TOKEN`	—	Shared secret for agent-mcp to backend auth
`STUDIO_AGENT_RATE_LIMIT`	`120`	Requests per minute per token
`STUDIO_AGENT_MCP_PORT`	`8090`	Agent MCP server port
`STUDIO_LOG_LEVEL`	`INFO`	Logging level

Troubleshooting

Agent can’t connect

Verify the agent-mcp container is running: docker compose ps
Check health: curl http://localhost:3000/agent-mcp/health
Verify STUDIO_AGENT_SERVICE_TOKEN is set in both environments
Check logs: docker compose logs agent-mcp

Token rejected

Confirm the token hasn’t expired
Verify it hasn’t been revoked
Check rate limits

OAuth flow fails

Ensure client_id and client_secret are correct
Check the grant_type is client_credentials or refresh_token
Verify the OAuth client hasn’t been revoked

REST API

Full REST API reference for all endpoints

Security

Authentication, token security, and encryption

Deployment

Deploy and connect to the MCP server

SSL/HTTPS Setup

Enable HTTPS for production Agent MCP access

Configuration

Agent MCP environment variables

Troubleshooting

Common issues and debugging tips

REST API

Agent MCP

​Quick Start

​1. Start Services

​2. Set Service Token

​3. Create an Agent Token

​4. Connect Your MCP Client

​Authentication Methods

​Temporary Tokens

​OAuth2 Client Credentials

​Comparison

​MCP Client Configuration

​Claude Code

​Cursor

​Production (with SSL)

​Tool Reference

​Connections (8 tools)

​Tools (7 tools)

​Resources (5 tools)

​Prompts (5 tools)

​Deploy (3 tools)

​Export/Import (2 tools)

​History (3 tools)

​Monitoring (3 tools)

​Flow (1 tool)

​Rate Limiting

​Activity Log

​Security Best Practices

​Environment Variables

​Troubleshooting

​Agent can’t connect

​Token rejected

​OAuth flow fails

​See Also

REST API

Security

Deployment

SSL/HTTPS Setup

Configuration

Troubleshooting

Quick Start

1. Start Services

2. Set Service Token

3. Create an Agent Token

4. Connect Your MCP Client

Authentication Methods

Temporary Tokens

OAuth2 Client Credentials

Comparison

MCP Client Configuration

Claude Code

Cursor

Production (with SSL)

Tool Reference

Connections (8 tools)

Tools (7 tools)

Resources (5 tools)

Prompts (5 tools)

Deploy (3 tools)

Export/Import (2 tools)

History (3 tools)

Monitoring (3 tools)

Flow (1 tool)

Rate Limiting

Activity Log

Security Best Practices

Environment Variables

Troubleshooting

Agent can’t connect

Token rejected

OAuth flow fails

See Also